AGENTS.md

Brigade is a zero-runtime-dependency Python CLI for agent memory, handoffs, and local guardrails, published to PyPI as brigade-cli. Source lives in src/brigade/, tests in tests/, harness/depth/include manifests in src/brigade/templates/.

Installing, evaluating, or adapting Brigade for a user's workspace? Follow docs/agents-guide.md instead. This file is for developing Brigade itself; the contributor policy lives in CONTRIBUTING.md.

Definition of Done

./scripts/verify

It runs the same gates CI blocks on: ruff lint, ruff format check, the version-sync check, mypy, and the full pytest suite with the coverage floor. Report the actual result, paste any failure verbatim, and never claim success you did not observe.

CI-only jobs still cover work that is slower, platform-oriented, or depends on extra checkout/install context: content-guard, repo-metadata, install-from-source, quickstart-smoke, and windows-native-acceptance. The local ./scripts/verify gate is the fast completion gate; do not treat it as a replacement for those CI-only release and public-repo checks.

Setup, if .venv/ is missing:

python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"

Rules

Format: trigger, then the rule, then what to do instead.

• About to report a code change as complete: run ./scripts/verify first. If you cannot run it, do not guess; report the exact command and error that blocked you.
• A test fails after your change: never weaken, skip, or delete the test to make it pass. Fix the code. If you believe the test itself is wrong, say so explicitly and get agreement before touching it.
• Pushing (only when explicitly asked): this repo has a content-guard pre-push hook. Never bypass it with git push --no-verify. Fix the flagged leak, or add a reviewed inline allow-tag (<!-- content-guard: allow <rule-id> -->) on the offending line.
• Unsure how to build, test, or release: never invent commands. Check pyproject.toml, .github/workflows/ci.yml, and CONTRIBUTING.md; if the answer is not there, report exactly what is missing.
• Exercising ingest, init, operator, or quickstart during development: never run them against the real operator workspace or your own home directory. Use a temp dir, the way the tests do: the tmp_target fixture in tests/conftest.py builds on tmp_path, and the manual smoke test in CONTRIBUTING.md targets $(mktemp -d).
• Writing templates, fixtures, or tests: no personal details, hostnames, IPs, account IDs, or live auth profiles. The content-guard CI job fails on them. Use obviously fake placeholders.
• Adding a runtime dependency, or a new top-level harness, depth, or include: needs a conversation first. Open an issue per CONTRIBUTING.md instead of landing it directly.
• Bumping the version: update pyproject.toml, src/brigade/__init__.py, and every template _brigade_version field together. ./scripts/verify checks the sync.
• Committing: use conventional commits. In escoffier-labs organizations and original solomonneas repositories, commits for substantial coding work should carry the coding agent's co-author trailer. External repositories and upstream third-party PRs remain trailer-free.

Orientation

• The CLI entry point is brigade.cli:main ([project.scripts] in pyproject.toml). Command families live in src/brigade/cli/ — one module per group (e.g. doctor.py, operator.py, init.py, work/); __init__.py builds the parser and dispatches to each module's register/dispatch.
• New harness adapter? Follow the step list in CONTRIBUTING.md (manifest, templates, KNOWN_HARNESSES, CI matrix, README table).
• Doctor checks return OK, WARN, FAIL, or MANUAL. Prefer WARN or MANUAL for optional wiring; FAIL means the profile is broken.
• docs/plans/ and docs/specs/ are gitignored scratch space; reviewed plans live at tracked docs/phase-*.md paths.

Memory Handoff

At the end of any substantial task that produced durable knowledge (root causes, decisions, gotchas), write a handoff to .claude/memory-handoffs/ using the format in .claude/memory-handoffs/TEMPLATE.md.

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
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

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.

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 rules, and when to use brigade update are in docs/update-channels.md.

brigade operator doctor --target ./my-repo prints ready: yes when the wiring is healthy. 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.

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

Tool	File it writes
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
Codex CLI	.codex/config.toml (merged surgically, other tables preserved)
Grok CLI	.grok/config.toml (same TOML shape as Codex)
VS Code	.vscode/mcp.json (secrets become inputs[])
OpenCode	opencode.json
Antigravity	~/.gemini/config/mcp_config.json (user-scoped)

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.

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):

Surface	Commands	Notes
Code graph	brigade code …	Callers, impact, context. Formerly GraphTrail.
Evidence log	brigade evidence …	Searchable ledger of runs and imports. Formerly MiseLedger.
Content Guard	brigade guard / brigade scrub	Secrets and private detail before publish.

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

Station	Install	Role
Agent Pantry	brigade add pantry	Encrypted browser-session and secret sync across machines
Token Glace	brigade add tokens	Compact noisy tool output before it burns context
Skillet	optional roster	Portable skills that reconcile can promote or roll back
Bootstrap Doctor	brigade add bootstrap-doctor	Audit OpenClaw bootstrap files (SOUL.md, TOOLS.md, AGENTS.md, IDENTITY.md, MEMORY.md, and the rest of the set) and trim oversize detail into cards
Notifications	brigade add notifications	Optional agent-notify binary for Discord, Telegram, or Signal. Status and setup planning only until you wire hooks or pass an explicit --send

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.

	Across harnesses	MCP, tools, and memory in one source	Review gate + receipts	Local files, no daemon
Brigade	yes	yes	yes	yes
mem0 / Letta / agentmemory	per-SDK	memory only	no	usually hosted or a server
add-mcp / chezmoi / config-sync	partial	MCP or dotfiles only	no	yes
Native harness memory	no	memory only	no	yes

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 or install schedulers (one scoped exception: brigade tools runtime start launches a local runtime process, only when you start it, until you stop it). 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)

What you type / say	Historical name	Notes
Code graph · brigade code	GraphTrail	Built in via brigade setup
Evidence log · brigade evidence	MiseLedger	Built in via brigade setup
Content Guard · brigade guard / scrub	content-guard	Embedded
Bootstrap Doctor	same	Full OpenClaw bootstrap set: SOUL, TOOLS, AGENTS, IDENTITY, MEMORY, and related session-start files

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
• 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.