Brigade

One command to start. One command to keep it maintained.

Built for coding agents to run end to end (install, setup, verify, handoffs), not as a human day-to-day terminal app. When an agent says tests passed, you get a file with the real exit code, a code graph of what changed (brigade code), and an evidence log you can search later (brigade evidence). Optional: one MCP and tools catalog across agents, and shared notes with a review gate. Brigade owns the memory-care primitives and runbooks. An external scheduler (cron, systemd, CI, your agent cron) invokes them. Local files. No daemon. No lock-in. Boundary: execution model.

Website · Docs · Install · Cookbook

An agent said "tests pass." This is the claim becoming a record: receipt, code graph, evidence log, rank.

The loop

Every piece of work Brigade touches runs the same circuit:

1. Intent and acceptance criteria go in.
2. Prior evidence and code impact attach to the brief.
3. Replaceable workers execute, bounded.
4. Verification runs with a real exit code.
5. The receipt, graph delta, and outcome land where the next run starts.

Work enters as intent and leaves as evidence.

Install

Default path: give the job to an agent. Paste something like this into Claude Code, Codex, Cursor, OpenClaw, or any agent with shell access:

Read https://github.com/escoffier-labs/brigade and follow AGENTS.md.
Install brigade-cli with pipx if missing. Run operator quickstart with
--dry-run first and show the plan. Then apply, run brigade operator doctor,
and report ready: yes. Keep existing memory layout. Do not touch remotes,
do not commit, stop before anything destructive.

The agent installs, runs brigade setup, wires harnesses, and leaves files on disk. You review when the gate is ambiguous or risky. You do not have to type the install path yourself.

If you prefer a shell (same commands the agent would run):

pipx install brigade-cli  # or: uv tool install brigade-cli
pipx ensurepath           # then open a new shell so `brigade` is on PATH
brigade setup             # install the verified native engines
brigade operator quickstart --target ./my-repo --harnesses codex

One and done (Claude Code). Instead of wiring repos one at a time, install the work-loop hooks once at user scope:

brigade work hooks install --scope user

From then on, every repo the agent opens gets the work brief injected at session start, and an unwired repo gets the exact brigade init command printed for the agent to run - so agents wire new repos themselves and the verified-work loop closes everywhere without another human command. Remove it any time with brigade work hooks uninstall --scope user; only Brigade-owned hook entries are touched.

Brigade prints a one-line notice when a new release is out. It checks at most once a day through an anonymous request. Set BRIGADE_NO_UPDATE_CHECK=1 to disable it. Details are in docs/update-channels.md.

Two update channels exist and they are not interchangeable. Stable is the default: immutable, PyPI-published releases like 0.26.0, pinned exactly - what production and operator machines should run. Beta is the intentional development-machine channel for the 0.27 preview line: it pins the newest non-yanked brigade-cli==0.27.0.devYYYYMMDD wheel from PyPI into the existing user-global pipx environment, not a mutable Git main SHA. Stable pinners may deliberately install an exact release with pipx install brigade-cli==X.Y.Z or refresh through brigade update --channel stable. Channel ownership, beta selection and rollback rules, and when to use brigade update are in docs/update-channels.md.

brigade operator doctor --target ./my-repo --profile local-operator prints ready: yes when the wiring is healthy (without the profile flag, doctor runs the stricter internal-dogfood checks and a fresh repo reports not ready). The default footprint is small: AGENTS.md, SAFETY_RULES.md, a handoff template, and .brigade/ state. Add --dry-run to preview anything before it writes. Nothing leaves your machine.

Per-OS setup (apt, Homebrew, Scoop, PowerShell), workspace depth, and multi-harness installs: install guide, QUICKSTART.md, first 10 minutes. Homegrown setup already? brigade operator adopt plan.

Contributing? See Your first PR in CONTRIBUTING.md for starter issues, the 48-hour claim convention, and local verification (Local dev: content-guard scan for docs-only changes; ./scripts/verify for code).

Auditable agents: every action leaves a receipt

An agent that reports "tests pass, nothing else changed" is making a claim. Brigade turns the claim into a record. Run any check through Brigade and it writes a receipt: the command, the real exit code, the graph delta, the git state.

brigade work verify run --target . --command "pytest -q" --capture brigade-work

// .brigade/work/verify-runs/20260722-033355-work-verify-298ff5/receipt.json (abridged)
{
  "run_id": "20260722-033355-work-verify-298ff5",
  "status": "completed",
  "duration_seconds": 15.18,
  "commands": { "check": { "argv": ["pytest", "-q"], "returncode": 0 } },
  "code_graph_delta": { "changed_symbol_count": 0 },
  "git": { "branch": "main", "dirty_files": 0 }
}

Receipts land in the evidence log (brigade evidence), a Go engine installed by brigade setup (historically shipped as MiseLedger). Every consequential action elsewhere in Brigade (a memory write, a skill promotion, a sync) is logged the same way. brigade evidence search answers "what ran, when, and what did it change" from files, weeks later. Cross-model dispatches through brigade run carry the same paper trail. When someone asks what your agents did this week, the answer comes from receipts you can grep, not from scrollback. Capability page.

Code graph, built in

The code_graph_delta line in that receipt comes from the code graph (brigade code), a Rust engine installed by brigade setup (historically shipped as GraphTrail, digest-verified, no toolchain required). It indexes your repo once and keeps up incrementally. On this repository a sync pass over 652 files and 10,405 symbols reports in well under a second. A receipt names the exact symbols a change touched, and your agents stop grepping and start asking structural questions:

$ brigade code impact _write_receipt
test_runbook_closeout_imports_failed_steps  --calls@31--> _write_receipt
test_runbook_closeout_without_import_flag   --calls@45--> _write_receipt

$ brigade code context "verify receipts"
## Entry Points
- function `_verify_receipts` at src/brigade/work_cmd/verification.py:185-192
- function `_iter_verify_receipts` at src/brigade/workflow_cmd.py:142-167

The graph feeds the rest of Brigade instead of sitting idle: brigade run prepends a context pack when a graph exists, so a dispatched model starts from callers and blast radius instead of a cold grep, and an MCP server ships alongside so any harness can query the graph directly. Capability page.

One MCP and tool catalog, synced into every tool

Every agent tool reads its MCP servers from a different file in a different shape. The same servers wired across Claude Code, Cursor, Codex, VS Code, OpenCode, and Antigravity means hand-editing six configs and keeping them in sync forever. Brigade keeps one canonical catalog and merges it into each tool's native config for you.

brigade mcp init                  # scaffold .brigade/mcp.json
brigade mcp add --name github --command npx \
  --args "-y @modelcontextprotocol/server-github" \
  --env GITHUB_AUTH_ENV=ref:BRIGADE_GITHUB_AUTH_ENV
brigade mcp sync                  # dry-run: show the diff for every tool
brigade mcp sync --write          # merge into each tool's config
brigade mcp verify                # check initialize + tools/list at runtime

Run brigade mcp sync and you get the per-tool plan, server by server, before a single file changes:

brigade mcp sync (dry-run): ~/my-repo
claude       github               missing        -> create
claude       sentry               missing        -> create
cursor       github               missing        -> create
cursor       sentry               missing        -> create
codex        github               missing        -> create
codex        sentry               missing        -> create
vscode       github               missing        -> create
vscode       sentry               missing        -> create
opencode     github               missing        -> create
opencode     sentry               missing        -> create

Dry-run by default. Merges by server key, so servers you added by hand are never touched. Secrets are written as ${VAR} references, never inlined. Ownership lives in a gitignored sidecar, so a fresh clone re-syncs without conflict. Tools and skills get the same treatment via brigade tools sync: one reviewed catalog, projected into each harness's native format. Full merge rules: docs/mcp-sync.md. Evaluating options first? The comparison page.

Shared memory and verified learning

Writer harnesses leave handoff notes as they work. Brigade lints, guards, and classifies each one. Safe, targeted notes file themselves into durable memory. The ambiguous few wait for your review. Every consequential action is logged to a plain file you can grep, diff, and prune.

Memory stays two layers deep: knowledge cards hold the detail, MEMORY.md stays a slim one-line-per-card index that loads every session. brigade memory care scan flags stale or contradictory cards instead of letting them rot, and brigade evidence search plus exported briefs mean the next session starts where this one stopped.

Filing notes is the first loop. The second loop earns trust: Brigade promotes a learned skill only when a real signal proves it helped, and rolls it back the moment a signal says it broke. The model never grades its own work.

$ brigade outcome rank
- brigade-work      score=0.692  helped=675  hurt=260
- ultra-work-scout  score=0.563  helped=50   hurt=24
- memory-handoff    score=0.490  helped=8    hurt=2

• brigade outcome capture records a verify run's real exit code against the skill that produced it.
• brigade outcome score ranks by a Wilson lower bound, so two lucky passes never outrank twenty vetted runs.
• brigade outcome reconcile is the gate: dry-run by default, --apply installs a skill that earned it or rolls a regressed one back.
• brigade outcome explain prints the full signal trail behind any decision, so every promotion is as auditable as the runs that earned it.

Scores are recomputed from the stored receipts every time you read them, so upgrading Brigade can move numbers with no new runs. Which failures count against a seat and which neutralize is in docs/outcome-scoring.md.

The ledger is plain JSON and markdown under memory/outcome/, tracked in git, readable without Brigade. brigade init wires a brigade-work skill into each harness so agents run this loop without being told. With Claude Code it also installs project-scoped hooks that redirect raw test commands through verify runs.

Optional stations

Built in (via brigade setup):

Optional stations (add when you need them). Core works with none installed. brigade status health-checks whatever is present.

Upgrading from standalone GraphTrail or MiseLedger installs? brigade setup replaces both. The old brigade add graphtrail / add evidence paths remain as compatibility shims. Engine binaries and some paths still use the historical names. The operator surface is brigade code and brigade evidence. Details: wiring guide, station contract.

Beyond the daily loop, the same review-and-receipt pattern covers cross-model runs (brigade run dispatches one bounded task across your roster), security scans, friction mining, research reports, and fleet health. All of it stays behind brigade extras on until you ask. The full tour: docs/overview.md.

Why not something else?

• mem0, Letta, agentmemory, and friends are memory layers for apps you are building, usually behind an API or a server. Brigade is for the agent CLIs you already run, and it is file-first: your memory is markdown in your repo, reviewable in git, readable without Brigade.
• add-mcp, chezmoi, and config-sync scripts move MCP or dotfiles around, but they sync one thing with no review gate and no receipt. Brigade keeps MCP servers, tools, skills, and memory in one canonical source, shows the per-tool diff before any write, and leaves a receipt you can roll back.
• Native harness memory is a per-tool silo. It does not cross harnesses, and it writes without review. Brigade gives every tool one shared format and one canonical owner, with a review gate in between.
• Already running Hermes, or any self-improving agent? Keep it. Brigade is the verification layer on top: it promotes a skill only when a real signal confirms it, keeps every learned skill as portable markdown in your git, and runs one loop across your whole fleet.
• A plain CLAUDE.md / AGENTS.md works great until it bloats past the context budget and goes stale. Brigade keeps bootstrap files slim, moves detail into indexed cards, and flags staleness instead of trusting last month's facts forever.
• A daemon or hosted service would be simpler to demo and worse to trust. Brigade writes local files when you run a command, and that is all it does. See the execution model.

What Brigade is not

Brigade is not a hosted memory service, a daemon, or an automatic release bot. It does not run in the background. Scheduling stays with the operator (see the execution model). It does not push to GitHub, publish packages, save every note automatically, or skip review for ambiguous, risky, or failed notes. brigade work brief and related status surfaces may report notification readiness or suggest installing the notifications station, but Brigade never sends a message unless the operator uses an explicit send action such as brigade pantry expiry-alert --send. That pause is the point: agent memory should be useful, not noisy.

And it is not the other projects that share the name. This Brigade is the AI-agent operator CLI from escoffier-labs/brigade, installed with pipx install brigade-cli. It is not the CNCF/Microsoft Brigade for Kubernetes event scripting (archived 2022), the Spinabot Brigade agent crew, or the 2017 brigade Python package that became Nornir.

Why I built this

I run an always-on OpenClaw agent next to daily Codex and Claude Code sessions. Every one of those tools wakes up empty, and whatever a session learned scattered across tool-specific folders and died there. Two incidents shaped the design: a "dreaming" job that promoted raw session fragments straight into memory bloated MEMORY.md past the bootstrap budget, so every session started truncated and nobody noticed for weeks. And 195 handoff notes sat unread across 35 repos because an ingester had a hardcoded allowlist and nothing warned about the gap. Silence is the failure mode. Every part of Brigade that lints, warns, or writes a receipt exists because something once failed in silence. The full production stack, now 482 cards across daily multi-agent work, is documented in the Cookbook.

Names (public vs historical)

Kitchen language (brigade de cuisine, mise en place, station nicknames) is brand and deep docs. Commands and product surfaces stay plain: receipt, code graph, evidence log, sync, handoff.

Who runs what: agents install, set up, verify, and write handoffs. Humans set policy and review gates when something is ambiguous or risky. The CLI is the control plane the fleet drives, not a tool you are expected to operate by hand all day.

Harnesses

Nineteen harnesses get handoff inboxes and ingest coverage, from Codex, Claude Code, and Cursor to Goose, Aider, and OpenHands. Most also get projected tools and skills in their native format. The per-harness matrix is in the technical guide.

Questions

@brigadeclaw answers questions about Brigade on X. Every sentence it posts cites the pinned documentation it came from, and it stays silent rather than guessing. How it works, including the gates and the refusals: brigade.tools/brigadeclaw.

Docs

• First 10 minutes · Overview · Technical guide
• Execution model · Memory care · MCP sync
• Security and Content Guard · Handoff promotion
• Command inventory · Station contract
• Maintainers · Governance · Security · Contributing · Roadmap

License

MIT. See LICENSE.

Project identity: GitHub escoffier-labs/brigade, website brigade.tools, PyPI brigade-cli, command brigade. The product name comes from a kitchen line (brigade de cuisine): coordinated stations, prep before service. You do not need the kitchen glossary to install or run it. Set up rules, memory, tools, and receipts before the session gets expensive.

It is early-stage and moving fast. If you hit a broken workflow, a confusing command, or a setup issue, open an issue and I will get it fixed.