brigade-cli 0.6.0

Run your agent brigade: an operator-system CLI that bootstraps, checks, and operates agent workspaces across harnesses.

Brigade

Run your agent brigade.

Public-safe workspace bootstrap, memory handoffs, and publish guards for real agent setups.

brigade is the operator-system CLI for agent workspaces. It gives you the workspace skeleton, handoff inbox, conservative ingester, and publish guards that make a multi-agent setup usable without leaking private junk into public repos.

What this is

Mise en place means "everything in its place before the work starts." In a kitchen, that is chopped mirepoix, clean pans, labels, and a station that does not make you hunt for salt & butter mid-service. For agents, it is the same idea: rules, memory, tools, handoff inboxes, publish guards, and boring verification already laid out before the session gets expensive.

This package lays down a clean starting point for an agent workspace or a repo that needs durable memory handoffs. It is meant for people running real tools, real docs, and real automation across OpenClaw, Claude Code, Codex, Hermes, or a similar harness.

The cookbook explains the why. This package gives you the kitchen.

What you get

• sanitized bootstrap files for agent behavior, safety, tools, identity, and memory
• a canonical memory layout where one configured owner holds durable knowledge
• a shared .claude/memory-handoffs/ inbox for Claude Code, Codex, and other side harnesses
• starter memory cards and routing rules
• multi-workspace handoff patterns for people administering more than one agent setup
• memory-care staleness checks so durable cards do not quietly rot
• TokenJuice output-compaction guidance for Claude Code and Codex, including wrapper notes and savings expectations
• content-guard publish gates so private infrastructure does not leak into public docs
• adapter fragments for OpenClaw (tested), Hermes (stubbed), and generic harnesses
• doctor checks that prove the system is wired before you trust it

What you do not get

• private hostnames, IPs, account IDs, or personal details
• live auth profiles or OAuth tokens
• cron jobs that post publicly by default
• destructive automation or write-enabled integrations without explicit opt-in

Install

pipx install brigade-cli

Or, to track main:

pipx install git+https://github.com/escoffier-labs/brigade

The workspace config directory is .brigade (older .solo-mise installs are still read), and the solo-mise command is a deprecated alias for brigade.

Quick path

Run brigade init with no flags for the interactive picker:

brigade init --target ~/agent-kitchen

For CI or scripts, pass flags directly:

brigade init --target ~/agent-kitchen --depth workspace --harnesses claude,codex,openclaw
brigade init --target ./repo --depth repo --harnesses codex
brigade init --target ./repo --harnesses none           # generic install

Once installed, brigade doctor verifies the wiring and brigade status reports over the station registry.

Two axes: depth + harnesses

brigade installs material on two independent axes:

Depth, how much shared baseline you want:

Depth	Installs
repo (default)	AGENTS.md, SAFETY_RULES.md, INSTALL_FOR_AGENTS.md, hooks/pre-push, .brigade/policies/public-repo.json
workspace	repo + MEMORY.md, TOOLS.md, USER.md, SOUL.md, IDENTITY.md, HEARTBEAT.md, memory/cards/, starter cards

Harnesses, which tools you actually use:

Harness	Role	Adds
claude	writer	CLAUDE.md + .claude/memory-handoffs/ inbox
codex	writer	.codex/memory-handoffs/ inbox (AGENTS.md is in the baseline)
openclaw	reader	.brigade/openclaw/ config fragments + cron stubs
hermes	reader	.brigade/hermes/ adapter fragments (experimental)

Includes, optional add-ons:

Include	Adds
publisher	.brigade/policies/public-content.json + content-safety memory card + scrub-cache

Picking your harnesses

Four common combos:

• Claude Code only: --harnesses claude, the lightest setup, just one writer.
• Claude Code + OpenClaw: --harnesses claude,openclaw, durable memory owner (OpenClaw) plus side writer (Claude Code).
• Claude Code + Codex + OpenClaw: --harnesses claude,codex,openclaw, both writers feed into OpenClaw as the canonical owner.
• Codex + OpenClaw: --harnesses codex,openclaw, Codex-first user with OpenClaw as the canonical store.

The canonical memory owner is picked automatically by priority (openclaw > hermes > claude > codex > this-repo). Override with --owner.

Re-running brigade init against an existing target is safe. It refuses to overwrite tracked files without --force, and the .gitignore block it manages is replaced between its markers without touching the rest of your file.

See QUICKSTART.md for setup, verification, and the ingest flow.

Managed stations

Some stations can install and wire external tools for you. Run brigade add <station> to install any tool attached to that station that is not already on your PATH, then wire its default config. Tools are never imported in process; Brigade shells out to each CLI, so the boundary stays model-neutral and mixed-language.

brigade add memory   # memory-doctor + bootstrap-doctor
brigade add guard    # content-guard
brigade add tokens   # tokenjuice

The four managed tools:

Station	Tool	What it does
memory	memory-doctor	memory index health, dead-link lint, handoff counts
memory	bootstrap-doctor	bootstrap-file size and limit audit
guard	content-guard	policy-driven content scanning
tokens	tokenjuice	output compaction via host hooks

brigade doctor folds installed tools into its report and surfaces each tool's own health. A tool that is not installed is never a failure: it shows up as a non-failing [todo] hint telling you to run brigade add <station>. That keeps doctor green on a bare host while still pointing you at what is available to add.

What a green doctor looks like

brigade doctor: target /home/you/agent-kitchen (generic)
  [ok]   bootstrap: AGENTS.md              /home/you/agent-kitchen/AGENTS.md
  [ok]   bootstrap: CLAUDE.md              /home/you/agent-kitchen/CLAUDE.md
  [ok]   bootstrap: MEMORY.md              /home/you/agent-kitchen/MEMORY.md
  [ok]   bootstrap: TOOLS.md               /home/you/agent-kitchen/TOOLS.md
  [ok]   bootstrap: USER.md                /home/you/agent-kitchen/USER.md
  [ok]   bootstrap: SAFETY_RULES.md        /home/you/agent-kitchen/SAFETY_RULES.md
  [ok]   bootstrap: INSTALL_FOR_AGENTS.md  /home/you/agent-kitchen/INSTALL_FOR_AGENTS.md
  [ok]   handoff: inbox                    /home/you/agent-kitchen/.claude/memory-handoffs
  [ok]   handoff: TEMPLATE.md              /home/you/agent-kitchen/.claude/memory-handoffs/TEMPLATE.md
  [ok]   handoff: processed/               /home/you/agent-kitchen/.claude/memory-handoffs/processed
  [ok]   memory: cards/                    /home/you/agent-kitchen/memory/cards
  [ok]   publish: hooks/pre-push           /home/you/agent-kitchen/hooks/pre-push
  [ok]   publish: content-guard            /home/you/repos/content-guard

summary: 14 checks, 0 failed, 0 manual

Anything [warn] is fine; [fail] means the install is incomplete. The openclaw and hermes harnesses add their own checks on top.

Privacy

brigade makes no network calls. It does not phone home, collect telemetry, or sync anything to a server. Everything happens on your local filesystem against the templates packaged with the install. The only file that touches the network is the pre-push hook, and it runs the local content-guard scanner against your own commits before they leave the machine.

The design

One memory owner stays canonical (typically OpenClaw or Hermes when present, otherwise this-repo). Writer harnesses drop handoffs into their own inboxes; the ingester scans all of them.

Claude Code              Codex
     |                     |
     v                     v
.claude/memory-handoffs/ .codex/memory-handoffs/
     \                   /
      \                 /
       v               v
      brigade ingest
              |
              v
  memory/cards/*.md, TOOLS.md, USER.md,
  rules/*.md, .learnings/*.md

The ingester is intentionally conservative. Safe card handoffs become cards. Targeted updates append to the right file. Ambiguous material gets kicked out for review instead of being trusted automatically.

For users running multiple agent homes, treat the owner workspace as the hub. Remote or secondary workspaces can write handoffs into their own per-harness inboxes, then a trusted sync pulls those files into a staging inbox on the owner. That keeps agents informed about what happened elsewhere without creating multiple canonical memories.

Token-heavy terminal work gets the same treatment: make the wrapper explicit, make the escape hatch obvious, and tell every harness what is happening. The TokenJuice starter card documents Claude Code's PreToolUse wrapper path, Codex's hook setup, and the savings model.

Related

• Cookbook: the long-form companion guide and reference docs
• content-guard: the publish-gate scanner used by the pre-push hook
• OpenClaw: the reference memory owner

License

MIT