README.md

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.

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 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
• writer-specific Memory Handoff inboxes, such as .claude/memory-handoffs/ for Claude Code and .codex/memory-handoffs/ for Codex
• 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
• built-in agent workspace security scan for secrets, permissions, hooks, MCP configs, supply-chain patterns, and instruction risks
• adapter fragments for OpenClaw (tested), Hermes (stubbed), and generic harnesses
• doctor checks that prove the system is wired before you trust it

Browse the public template index in templates/. The installable source files live under src/brigade/templates/; root workspace files are local dogfood state and stay ignored.

See ROADMAP.md for the daily-driver, scanner inbox, chat-surface scanner, and memory-card decay roadmap.

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.

Run a brigade

brigade run "<task>" is the aboyeur path. One orchestrator plans the work, Brigade dispatches assigned workers through their own CLIs, then the orchestrator synthesizes the final answer. It is intentionally bounded: two orchestrator calls plus the worker calls in the plan.

Start with a roster:

brigade roster init
brigade roster doctor

That writes .brigade/roster.toml with a Codex orchestrator, a Codex coder, and an optional Ollama local researcher:

orchestrator = "chef"

[agents.chef]
cli = "codex"
role = "Plan the work, choose useful workers, and synthesize the final answer."

[agents.local_researcher]
cli = "ollama:llama3.3"
role = "Research locally and summarize useful findings."
timeout_seconds = 300

[agents.coder]
cli = "codex"
role = "Make precise code changes and report what changed."

[limits]
max_workers = 4
timeout_seconds = 600
allow_models = ["codex", "ollama:*"]

Edit the roles, CLI refs, and timeouts to match the tools on your machine. limits.timeout_seconds is the default per-agent timeout. agents.<name>.timeout_seconds overrides it for one agent. Then run:

brigade run "review this repo and suggest the next implementation step"
brigade run "plan the migration" --dry-run
brigade run "review this repo" --show-plan
brigade run "review this repo" --verbose
brigade run "review this repo" --cwd /path/to/repo
brigade run "review this repo" --handoff
brigade run "review this repo" --read-only
brigade run "review this repo" --read-only --inspect
brigade dogfood init --target /path/to/repo
brigade dogfood status
brigade dogfood
brigade dogfood next
brigade dogfood --target /path/to/repo
brigade work bootstrap
brigade work status
brigade work doctor
brigade work resume
brigade work brief
brigade work brief --json
brigade work next
brigade work next --json
brigade work tasks
brigade work task add "build the next slice"
brigade work task add --from-next
brigade work task done <task-id>
brigade work import add --kind task --source slack "refresh the stale memory card"
brigade work import list
brigade work import validate imports.jsonl
brigade work import ingest imports.jsonl
brigade work import memory-care
brigade work import triage
brigade work import promote <import-id>
brigade work import promote --all --source memory-care --kind task
brigade work import dismiss <import-id> --reason "not actionable"
brigade work run
brigade work run --queue-next
brigade work run "review today's changes"
brigade work start "next slice"
brigade work note "wired parser and tests"
brigade work end --note "tests passed" --handoff
brigade work list
brigade work latest
brigade work recap --since 2026-05-26

Common brigade run flags:

• --dry-run prints planned assignments as JSON and stops before worker dispatch.
• --show-plan prints assignments before a normal run.
• --verbose prints the plan, worker statuses, and synthesis status.
• --cwd sets the working directory for agent CLI calls.
• --handoff writes a Memory Handoff for a successful non-dry run.
• --inspect prints the same artifact summary as brigade runs show.
• --read-only tells the orchestrator and workers to inspect and recommend only.

For codex agents, --read-only also passes codex exec --sandbox read-only. Other adapters receive the prompt policy only.

The cli values are adapters for installed command-line tools: codex, claude, and ollama:<model>. Brigade shells out to those tools and keeps no provider keys. Run brigade roster doctor to validate roster syntax and check which CLIs are on PATH.

Dogfood

brigade dogfood is the shortcut for using Brigade on itself or another trusted repo. It uses a built-in Codex-only roster, read-only prompt policy, normal run artifacts, a default Memory Handoff, and an artifact summary.

Set it up once:

brigade dogfood init --target /path/to/repo

That writes local defaults to .brigade/dogfood.toml, which is gitignored because it stores machine-local paths and preferences. New dogfood configs default handoffs to .codex/memory-handoffs/ because the dogfood roster is Codex-driven. Pass --handoff-inbox if your memory owner ingests a different path.

Daily commands:

• brigade dogfood runs the configured daily path from the repo.
• brigade dogfood "review today's changes" overrides only the task.
• brigade dogfood status checks paths, sandbox mode, CLI availability, ignore rules, and the latest run.
• brigade dogfood latest shows the latest configured dogfood run.
• brigade dogfood next prints the latest extracted next step.

Dogfood writes summary.md beside each run's JSON artifacts when a final answer or next step exists. It defaults to a 600 second per-agent timeout. Trusted-workspace runs use Codex's danger-full-access sandbox setting by default so repo inspection works on hosts where native read-only sandboxing blocks shell inspection.

Useful switches:

• --no-handoff skips the dogfood handoff.
• --no-inspect skips the artifact summary.
• --native-read-only-sandbox uses Codex's native read-only sandbox when the host supports it.

CLI runs write artifacts by default under .brigade/runs/<id> below --cwd; dogfood runs use .brigade/runs/<id> below the configured target:

File	Contents
run.json	task, cwd, orchestrator, mode flags, status, artifact path, handoff path, timestamps, and duration
roster.json	effective orchestrator, agents, limits, allow-list, and timeouts
plan-attempts.json	raw planner outputs, parse status, and parse errors from initial/correction attempts
plan.json	parsed worker assignments
worker-results.json	worker status, details, and text output for non-dry runs
synthesis.json	orchestrator synthesis status, detail, and raw text for non-dry runs
final.txt	final synthesized answer for non-dry runs
summary.md	dogfood summary with run metadata, final answer, and extracted next step when present

Use --output-dir <path> to pick the artifact directory, or --no-artifacts for a throwaway run.

Daily Work Loop

Use brigade work bootstrap once per repo. It writes or verifies .brigade/dogfood.toml, creates local artifact directories, creates the handoff inbox, updates .gitignore, and reports readiness.

Start-of-day commands:

• brigade work brief shows branch state, active sessions, pending tasks, import counts, latest dogfood run, and the command to continue.
• brigade work status is the quick dashboard for branch state, dogfood readiness, paths, latest run, and extracted next step.
• brigade work doctor checks dogfood config, security config, evidence bundles, Codex CLI, artifact paths, handoff inbox, ignore coverage, and latest run context.
• brigade work resume shows the active or latest session, latest dogfood run, extracted next step, and suggested command.
• brigade work next prints only the next task. Add --json for wrappers.

Task ledger commands:

• brigade work tasks lists .brigade/work/tasks.json.
• brigade work task add "..." queues a task manually.
• brigade work task add --from-next promotes the latest extracted dogfood next step.
• brigade work task done <task-id> closes queued work.

Import inbox commands:

• brigade work import add "..." creates a scanner-ready local import.
• brigade work import validate imports.jsonl checks scanner output against docs/import-schema.md.
• brigade work import ingest imports.jsonl ingests scanner output.
• brigade work import memory-care converts memory/cards/decay/refresh-queue.json into imports.
• brigade work import chat-sweep converts .brigade/chat-memory-sweeps/latest.json issues into imports.
• brigade work import triage groups pending imports by source and kind.
• brigade work import show <import-id> inspects one import.
• brigade work import dismiss <import-id> removes noise.
• brigade work import promote <import-id> promotes one reviewed import into the task ledger.
• brigade work import promote --all --source memory-care --kind task batch-promotes filtered imports.

Imports are stored under .brigade/work/imports/inbox.jsonl, stay gitignored, and do not write memory directly.

Run the daily loop with brigade work run. It opens a work session, resolves the next task, runs brigade dogfood, and closes completed ledger tasks after successful runs. Then it ends the session, writes a work-session Memory Handoff by default, and prints a recap.

Useful work run switches:

• --queue-next queues the successful run's extracted next step for the next session.
• --title names the session.
• --no-handoff skips the work handoff.
• --dogfood-handoff also lets the underlying dogfood run write its own handoff.
• Passing a task overrides the resolved next step.

Manual session commands:

• brigade work start "title" opens .brigade/work/<id>/, records starting context, and writes start.md.
• brigade work note "checkpoint" appends a timestamped note to the active session.
• brigade work end --note "what happened" closes the active session and writes end.md.
• brigade work end --handoff also writes a Memory Handoff.

Memory And Bootstrap Health

Memory and bootstrap readiness are part of the same operating-system health story. brigade doctor checks installed bootstrap files against hard byte budgets so overgrown files fail before agents load truncated context.

It also checks:

• memory/cards/*.md budgets
• MEMORY.md card links under memory/cards/
• memory-care freshness from memory/cards/decay/scan-latest.json
• corrupt scan or refresh-queue JSON once the loop is wired

Workspace installs include .brigade/memory-care.example.json as a scanner wiring contract for whatever scheduler or memory owner produces the decay files. They also include .brigade/chat-memory-sweep.example.json for nightly chat/session sweep summaries. Missing memory-care state is advisory for fresh installs. Bootstrap truncation is a hard failure to prevent, not a cosmetic warning.

Inspect local work sessions with:

• brigade work list
• brigade work latest
• brigade work show <session-id-or-path>
• brigade work recap
• brigade work recap --since YYYY-MM-DD

Inspect a completed run without opening each JSON file:

brigade runs list --cwd /path/to/repo
brigade runs latest --cwd /path/to/repo
brigade runs show .brigade/runs/<run-id>
brigade security init
brigade security fix
brigade security scan --target .
brigade security scan --target . --policy public-repo
brigade security scan --target . --output-dir .brigade/security/latest
brigade security enrich --target .
brigade security review
brigade security suppress <fingerprint> --reason "reviewed false positive"
brigade security unsuppress <fingerprint>
brigade security scan --target . --import-findings

Use --handoff to bridge a completed run back into the memory system.

Handoff behavior:

• By default it writes a reviewable handoff to .claude/memory-handoffs/ under --cwd.
• Use --handoff-inbox <path> for Codex, OpenCode, GPT, Hermes, OpenClaw, or another writer inbox.
• The handoff targets .learnings/LEARNINGS.md as a no-card document update.
• The normal brigade ingest route can review or ingest that handoff.
• If handoff writing fails after synthesis, Brigade still prints the final answer and keeps the final artifacts.
• Failed handoff writes exit nonzero and mark run.json as handoff-failed.
• --handoff is not allowed with --dry-run because dry runs have no final answer.

Live smoke test, using a temporary Codex-only roster:

tmpdir=$(mktemp -d)
smoke_cwd=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
mkdir -p "$tmpdir/.brigade"
cat > "$tmpdir/.brigade/roster.toml" <<'EOF'
orchestrator = "chef"

[agents.chef]
cli = "codex"
role = "Plan one small read-only task and synthesize a one-sentence final answer."

[agents.coder]
cli = "codex"
role = "Return exactly this sentence, with no shell commands and no extra prose: Brigade full dispatch integration worker succeeded."

[limits]
max_workers = 1
allow_models = ["codex"]
EOF

brigade roster doctor --target "$tmpdir"
timeout 360 brigade run \
  "Integration test: assign the coder worker to return its required success sentence, then synthesize one sentence saying the full Brigade dispatch path succeeded." \
  --roster "$tmpdir/.brigade/roster.toml" \
  --cwd "$smoke_cwd" \
  --output-dir "$tmpdir/run" \
  --handoff \
  --handoff-inbox "$tmpdir/handoffs" \
  --show-plan \
  --read-only

Codex may require --cwd to be a trusted git repo. The smoke keeps the roster, artifacts, and handoff inbox in the temp directory while running the agent CLIs from smoke_cwd. Live runs invoke authenticated model CLIs and may consume whatever quota or subscription those CLIs use. --dry-run still invokes the orchestrator, but it does not dispatch workers or synthesize.

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. The managed .gitignore block 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

security is a built-in station with no external managed tool yet.

Security commands:

• brigade security init writes gitignored local defaults to .brigade/security.toml.
• brigade security fix creates .brigade/security/ and refreshes the managed .gitignore block.
• brigade security scan --target . runs a read-only agent workspace security scan.
• brigade security scan --output-dir .brigade/security/latest writes redacted report artifacts.
• brigade security scan --import-findings turns findings into local brigade work import review items.
• brigade security enrich --target . enriches an existing report and writes enrichment artifacts.
• brigade security review inspects the latest evidence bundle, including enrichment when present.
• brigade security suppress <fingerprint> --reason "..." suppresses reviewed noise.
• brigade security unsuppress <fingerprint> removes stale suppressions.

The scanner covers:

• secrets and private keys
• broad permissions and risky hooks
• package scripts, GitHub Actions, and Python dependency config
• prompt-injection style instructions
• MCP configs, including remote transports, auto-approval, unpinned npx, and shell metacharacters
• MCP sensitive surfaces, including env values, broad file args, high-risk local commands, large server sets, and missing timeouts

Enrichment is explicit and post-scan. The default local provider only summarizes extracted indicators offline. The misp provider is opt-in through gitignored config and an API key environment variable.

brigade doctor and brigade work doctor report:

• security config health
• enrichment config health
• stale suppressions and missing suppression reasons
• latest evidence bundle status
• whether local security artifacts are ignored

Secret evidence is redacted before reports, artifacts, or imports are written. Security config supports policy presets (personal, public-repo, strict), fail_on, template scanning, fingerprint suppressions, and [enrichment] provider settings.

The current 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 missing optional tool is not a failure. It shows up as a non-failing [todo] hint telling you to run brigade add <station>.

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 by default. 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 normal exception is your own configured tooling:

• the pre-push hook runs the local content-guard scanner before commits leave the machine
• brigade security enrich can call MISP only when you explicitly configure and run the misp provider

The design

One memory owner stays canonical. That is typically OpenClaw or Hermes when present, otherwise this-repo. Writer harnesses drop handoffs into their own inboxes, and 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. A trusted sync can pull those files into a staging inbox on the owner. That keeps agents informed 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