brigade-cli 0.8.2

AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, Hermes, and OpenClaw.

Brigade CLI

AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, Aider, Goose, Continue, GitHub Copilot CLI, Qwen Code, Kimi Code, AdaL, OpenHands, Hermes, and OpenClaw.

Your agents run loops. Brigade keeps the receipts.

Harness agents ship smart models with empty heads. Every session they wake up knowing nothing about your machine, your rules, or what they learned yesterday, and whatever each one figures out scatters across tools and dies there.

Brigade is a local control plane for agent memory, work, tools, research, review, and release. Writer agents like Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, Aider, Goose, Continue, GitHub Copilot CLI, Qwen Code, Kimi Code, AdaL, and OpenHands leave handoff notes as they work. A memory owner like OpenClaw or Hermes ingests the ones worth keeping. Brigade lints, guards, and routes everything in between, and every consequential action lands a receipt in a plain file you can grep, diff, and prune. Nothing is published, pushed, or saved behind your back, and the shared memory never decays into a junk drawer.

It runs on the operator-controlled machine first, before any external service, whether that machine is a laptop, workstation, or VPS: local by default, loud about the exceptions. The GitHub repo is escoffier-labs/brigade, the PyPI package is brigade-cli, and the command is brigade.

Current Status

Brigade is usable now for real first-run workflows. The tested path is installing the CLI, running operator quickstart in a repo or operator workspace, checking operator doctor --profile local-operator, writing memory handoffs, projecting portable skills and tools, and using the local security scanner.

Quickstart keeps the first run scoped to the harnesses you select: a --harnesses codex setup watches the Codex handoff inbox, writes a local bootstrap handoff-ingest log, and leaves unwired side harnesses quiet until you add them.

It is still early-stage and being actively fleshed out. The current focus is hardening the first-run path, roadmap and command drift checks, daily operator loop, and local evidence closeouts. Expect sharp edges around advanced workflows, new harness adapters, repo-fleet evidence, and release-candidate evidence. If you hit a broken workflow, confusing command, missing adapter, or setup issue, open a GitHub issue in escoffier-labs/brigade and I will get it addressed as soon as I can.

Want an agent to set this up for you? Point it at this repository. The root AGENTS.md tells agents how to install Brigade, verify with doctor, adapt your existing homegrown workflow instead of replacing it, keep local generated folders out of commits, and stop before any remote or destructive action. The fuller walkthrough is in docs/agent-assisted-setup.md.

New here? Start with docs/first-10-minutes.md. Maintainers can use docs/support-response-templates.md for quick first replies to install, quickstart, doctor, commit-scope, and security questions.

Good first install:

pipx install brigade-cli
brigade operator quickstart --target ./my-repo --harnesses codex
brigade operator doctor --target ./my-repo --profile local-operator

For an OpenClaw or Hermes workspace instead of a code repo:

mkdir -p ~/agent-workspace
brigade operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
brigade operator doctor --target ~/agent-workspace --profile local-operator

For multiple agent surfaces:

brigade operator quickstart --target ./my-repo --harnesses codex,claude,opencode,antigravity,pi,cursor,aider,goose,continue,copilot,qwen,kimi,adal,openhands

If you use OpenClaw, Hermes, Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, or a mix of them, Brigade gives those tools a shared local pattern:

1. agents write handoff notes
2. the memory ingester scans, lints, and routes them
3. safe targeted notes become durable memory
4. ambiguous or risky notes wait for review
5. future sessions start with better context

It is intentionally local. Brigade writes files and review queues on the operator-controlled machine. It does not run a background service, publish releases, push to GitHub, send notifications, or rewrite permanent memory unless you explicitly run the command that does it.

Stack At A Glance

flowchart TB
    OWNER["<b>OpenClaw / Hermes</b><br/><i>canonical memory owner</i>"]
    MEMORY["<b>Durable memory</b><br/>MEMORY.md · cards · project context"]
    BRIGADE["<b>Brigade CLI</b><br/><i>local wiring · receipts · review queues</i>"]
    STATE["<b>.brigade/</b><br/>local config · scans · reports · closeouts"]

    OWNER -->|maintains| MEMORY
    BRIGADE -->|records| STATE
    BRIGADE -->|prepares reviewed handoffs for| OWNER

    subgraph WRITERS [" writer harnesses "]
        CODEX["<b>Codex CLI</b><br/>handoff writer"]
        CLAUDE["<b>Claude Code</b><br/>handoff writer"]
        OPEN["<b>OpenCode</b><br/>handoff writer"]
        MORE["<b>more CLI writers</b><br/>Antigravity · Pi · Cursor<br/>Aider · Goose · Continue<br/>Copilot · Qwen · Kimi · AdaL · OpenHands"]
        HERMES["<b>Hermes</b><br/>writer or owner"]
    end

    CODEX & CLAUDE & OPEN & MORE & HERMES == handoff drafts ==> BRIGADE
    MEMORY -. context .-> CODEX & CLAUDE & OPEN & MORE & HERMES

    subgraph LOCAL [" local operator lanes "]
        WORK["work sessions<br/>tasks · plans · verification"]
        SCAN["scanners<br/>security · chat · repo health"]
        RELEASE["release evidence<br/>candidates · smoke · waivers"]
    end

    BRIGADE --> WORK
    BRIGADE --> SCAN
    BRIGADE --> RELEASE

    classDef owner fill:#ef4444,stroke:#b91c1c,color:#fff;
    classDef brigade fill:#2563eb,stroke:#1d4ed8,color:#fff;
    classDef state fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef lane fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    class OWNER owner;
    class BRIGADE brigade;
    class MEMORY,STATE state;
    class WORK,SCAN,RELEASE,CODEX,CLAUDE,OPEN,MORE,HERMES lane;

Brigade was extracted from the solos-cookbook, a documented 24/7 multi-agent stack running in production. If you want the full picture of how Brigade fits into a real setup, start there, and a star helps other people find it.

Project Identity

• GitHub: escoffier-labs/brigade
• Website: brigade.tools
• Cookbook: solomonneas/solos-cookbook, the real-world multi-agent stack Brigade grew out of
• PyPI package: brigade-cli
• CLI command: brigade
• Core search terms: AI agent memory, agent handoffs, Codex memory, Claude Code memory, OpenCode handoffs, local-first agent workflow, AGENTS.md, agent guardrails

Why This Exists

Agent tools are getting good enough that people use more than one of them. That creates a boring but important problem: each tool learns a little bit, but the learning is scattered.

Brigade gives the setup a home base.

• OpenClaw or Hermes can be the main memory owner.
• Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, Aider, Goose, Continue, GitHub Copilot CLI, Qwen Code, Kimi Code, AdaL, OpenHands, and Hermes can write handoff notes.
• You can inspect and lint those notes before saving them.
• Local receipts show what happened during work, scans, and reviews.
• Risky actions stay manual.

The goal is not to make a giant automation machine. The goal is to make agent memory understandable, reviewable, and portable across harnesses.

Mise En Place

The name comes from the kitchen. A brigade de cuisine is the staff that runs the line, and mise en place, pronounced "meez", means everything is in its place before the work starts.

In a kitchen, that is the chef's first job: prep the station, label the ingredients, sharpen the tools, and make sure service does not depend on hunting for basics mid-rush. For agents, it is the same job: rules, memory, handoff inboxes, tools, guards, receipts, and verification paths set up before the session gets expensive.

That is the idea Brigade is built on. The chef owns the station, and every agent working in it should leave the setup clearer, safer, and easier for the next agent to use.

Start Small

Install:

pipx install brigade-cli

Set up a repo:

brigade operator quickstart --target ./my-repo --harnesses codex
brigade operator doctor --target ./my-repo --profile local-operator

Set up an agent workspace:

brigade operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
brigade operator doctor --target ~/agent-workspace --profile local-operator

Use --dry-run first if you want to preview the local files Brigade will write. To wire more than one agent surface, pass a comma-separated list such as --harnesses codex,claude,opencode,antigravity,pi,cursor,aider,goose,continue,copilot,qwen,kimi,adal,openhands.

If you already have a homegrown setup with scripts, handoff folders, crons, or process managers, use the adoption loop before changing it:

brigade operator adopt plan --target ~/agent-workspace --json
brigade operator adopt capture --target ~/agent-workspace --json
brigade operator adopt import-issues --target ~/agent-workspace --json
brigade operator migration status --target ~/agent-workspace --json
brigade operator migration doctor --target ~/agent-workspace --json
brigade operator migration consolidate --target ~/agent-workspace --surface shell_crontab --review-status needs-owner
brigade operator surfaces capture --target ~/agent-workspace --json
brigade operator surfaces doctor --target ~/agent-workspace --json
brigade operator surfaces review --target ~/agent-workspace --surface shell_crontab --status external-ok --all --reason reviewed-external-ownership
brigade operator surfaces reviews --target ~/agent-workspace --json
brigade operator surfaces import-issues --target ~/agent-workspace --json

adopt plan is read-only. adopt capture writes a redacted local snapshot under .brigade/operator/adoption/. adopt import-issues routes adoption gaps into the normal work inbox so the migration shows up in work brief and the daily loop. operator migration status/doctor/import-issues/consolidate rolls adoption state, surface review state, and pending migration work into one replacement-progress view, then lets a reviewed rollup supersede tiny record-level imports. operator surfaces capture/list/doctor/review/reviews/import-issues keeps a separate redacted registry for shell crontab, OpenClaw cron, and PM2 coverage under .brigade/operator/surfaces/. Scheduler and process surfaces are reported as counts, status totals, ordinal labels, review decisions, and fingerprints, not raw scheduler lines, job names, process names, command paths, host details, or environment values.

For a fuller first-run walkthrough and troubleshooting checklist, see docs/new-user-quickstart.md. For the shortest path, use docs/first-10-minutes.md. If quickstart fails, use the Quickstart setup problem issue form and include the redacted issue_report from brigade operator quickstart --json.

Write a handoff note:

brigade handoff draft \
  --target ./my-repo \
  --inbox codex \
  --title "What changed" \
  --summary "Short note future agents should know." \
  --content "### What changed

Put the durable note here."

Then run your memory owner's ingester. Safe targeted notes can be filed into long-term memory; ambiguous or risky notes stay visible for review.

That is the simplest useful version of Brigade: shared handoffs, local review, durable memory.

How Memory Handoffs Work

Each writer harness gets its own local inbox. Use brigade handoff draft --inbox <id> to write to the matching inbox, or select the harness with brigade operator quickstart --harnesses ....

Writer	--inbox / harness id	Local inbox	Brigade support
Codex CLI	codex	.codex/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Claude Code	claude	.claude/memory-handoffs/	handoff template, ingest source, tools, skills
OpenCode	opencode	.opencode/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Antigravity	antigravity	.antigravity/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Pi	pi	.pi/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Cursor	cursor	.cursor/memory-handoffs/	handoff template, ingest source, dogfood adapter, rules, skills
Aider	aider	.aider/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Goose	goose	.goose/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Continue	continue	.continue/memory-handoffs/	handoff template, ingest source, dogfood adapter, rules, skills
GitHub Copilot CLI	copilot	.copilot/memory-handoffs/	handoff template, ingest source, dogfood adapter, instructions, skills
Qwen Code	qwen	.qwen/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
Kimi Code	kimi	.kimi/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
AdaL	adal	.adal/memory-handoffs/	handoff template, ingest source, dogfood adapter, tools, skills
OpenHands	openhands	.openhands/memory-handoffs/	handoff template, ingest source, dogfood adapter, instructions, skills
Hermes	hermes	.hermes/memory-handoffs/	handoff template, ingest source, owner adapter fragments

OpenClaw is usually the canonical memory owner rather than a writer inbox. Add it with --harnesses openclaw,... when the workspace should own durable memory.

The memory owner, usually OpenClaw or Hermes, can ingest handoffs into the permanent memory files. Brigade keeps the handoff format consistent so different tools can contribute without each one inventing its own note style.

flowchart LR
    subgraph WRITERS [" writer inboxes "]
        C[".codex/memory-handoffs/"]
        CL[".claude/memory-handoffs/"]
        O[".opencode/memory-handoffs/"]
        A[".antigravity/memory-handoffs/"]
        P[".pi/memory-handoffs/"]
        CU[".cursor/memory-handoffs/"]
        AI[".aider/memory-handoffs/"]
        G[".goose/memory-handoffs/"]
        CO[".continue/memory-handoffs/"]
        GH[".copilot/memory-handoffs/"]
        Q[".qwen/memory-handoffs/"]
        K[".kimi/memory-handoffs/"]
        AD[".adal/memory-handoffs/"]
        OH[".openhands/memory-handoffs/"]
        H[".hermes/memory-handoffs/"]
    end

    DRAFT["Brigade handoff draft<br/>lint · guard · route"]
    REVIEW["operator review<br/>safe · ambiguous · risky"]
    OWNER["OpenClaw / Hermes<br/>memory owner"]
    MEM["durable memory<br/>cards · docs · learnings"]

    C & CL & O & A & P & CU & AI & G & CO & GH & Q & K & AD & OH & H --> DRAFT --> REVIEW
    REVIEW -->|safe targeted note| OWNER --> MEM
    REVIEW -->|needs judgment| INBOX["review inbox"]

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class C,CL,O,A,P,CU,AI,G,CO,GH,Q,K,AD,OH,H,DRAFT local;
    class REVIEW,INBOX review;
    class OWNER,MEM memory;

The important part is the boundary. The ingester should be conservative: safe card handoffs can become cards, targeted updates can append to the right file, and ambiguous material should be kicked back for review instead of trusted automatically.

Card Promotion And MEMORY.md

Long-term memory has two layers. Knowledge cards under memory/cards/ hold the detail: YAML frontmatter (topic, category, tags, created, updated) plus the durable facts. MEMORY.md is the index: one line per card, loaded at session start, never holding card content itself. When the ingester promotes a handoff, it creates or updates the card first, then adds or refreshes the one-line index entry. No-card handoffs append to the right document instead. Brigade records the receipt for every outcome but never edits MEMORY.md or cards itself; the memory owner does the writing.

flowchart LR
    HANDOFF["reviewed handoff<br/>create-card · update-card · no-card"]
    INGEST["memory ingester<br/>lint · guard · route"]
    CARD["memory/cards/&lt;name&gt;.md<br/>frontmatter + durable facts"]
    INDEX["MEMORY.md<br/>one-line index entry per card"]
    DOCS["TOOLS.md · USER.md<br/>rules/ · .learnings/"]
    RECEIPT["ingest receipt<br/>promoted · routed · skipped · failed"]

    HANDOFF --> INGEST
    INGEST -->|create-card / update-card| CARD --> INDEX
    INGEST -->|no-card| DOCS
    INGEST --> RECEIPT

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    classDef step fill:#f1f5f9,stroke:#64748b,color:#334155;
    class HANDOFF,INGEST,RECEIPT local;
    class CARD,INDEX,DOCS memory;

Keeping Cards Fresh

Memory degrades. Cards go stale, lose their backing evidence, or get superseded. brigade memory care scan is a read-only sweep over the card roots that checks freshness metadata (reviewed, fresh_until, confidence, evidence) and flags stale, expired, undersourced, contradictory, orphaned, and oversized cards. Flagged cards land in a refresh queue that routes into the work inbox, so a card that needs review shows up in the daily plan instead of rotting quietly. Brigade never edits or deletes a card automatically: the operator either refreshes it with a new reviewed date or archives it and drops the index entry.

flowchart LR
    CARDS["memory cards<br/>reviewed · fresh_until<br/>confidence · evidence"]
    SCAN["memory care scan<br/>read-only"]
    ISSUES["issues<br/>stale · expired · undersourced<br/>contradictory · orphaned · oversized"]
    QUEUE["refresh queue"]
    INBOX["work inbox<br/>daily plan candidates"]
    OPERATOR["operator review"]
    REFRESH["card refreshed<br/>reviewed date updated"]
    ARCHIVE["card archived<br/>index entry removed"]

    CARDS --> SCAN --> ISSUES --> QUEUE --> INBOX --> OPERATOR
    OPERATOR -->|still true| REFRESH -. fresh again .-> CARDS
    OPERATOR -->|no longer true| ARCHIVE

    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    classDef step fill:#f1f5f9,stroke:#64748b,color:#334155;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class CARDS,REFRESH memory;
    class SCAN,ISSUES,QUEUE,INBOX step;
    class OPERATOR,ARCHIVE gate;

The Local Loop

Brigade is built around a simple daily loop:

1. set up the repo or operator workspace
2. let agents work
3. run the memory ingester
4. review anything skipped, flagged, or ambiguous
5. save only the parts worth remembering

flowchart LR
    SETUP["quickstart<br/>local files"]
    WORK["agents work<br/>sessions & tasks"]
    HANDOFF["handoffs<br/>draft & lint"]
    REVIEW["operator review<br/>promote or defer"]
    MEMORY["durable memory<br/>only what is worth keeping"]
    RECEIPTS["receipts<br/>what happened"]

    SETUP --> WORK --> HANDOFF --> REVIEW --> MEMORY
    WORK --> RECEIPTS
    REVIEW --> RECEIPTS
    RECEIPTS -. better context .-> WORK

    classDef step fill:#f1f5f9,stroke:#64748b,color:#334155;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class SETUP,WORK,HANDOFF,RECEIPTS step;
    class REVIEW gate;
    class MEMORY memory;

This loop scales from one person using one repo or OpenClaw/Hermes workspace to a more serious operator setup with scanner inboxes, work receipts, release checks, and repo-fleet summaries. You do not need all of that on day one.

What Brigade Can Handle

For memory:

• install shared memory files, rules, and handoff templates
• keep one canonical memory owner
• lint handoff drafts before ingest
• scan handoff drafts with Content Guard before they become durable memory
• track which local inboxes the ingestor should watch
• reconcile ingester receipts so skipped, failed, routed, and promoted notes stay visible
• support OpenClaw, Hermes, Codex, Claude Code, OpenCode, Antigravity, Pi, Cursor, Aider, Goose, Continue, GitHub Copilot CLI, Qwen Code, Kimi Code, AdaL, and OpenHands conventions

For local work:

• record work sessions and verification receipts
• collect scanner findings into reviewable inboxes
• keep release-readiness evidence local and explicit
• project shared tool docs into harness-specific folders
• summarize repo/operator state before a work session

For safety:

• run Content Guard before push, release review, or handoff ingest
• import Content Guard findings into the work inbox for review
• keep generated state ignored by default
• avoid publishing, pushing, or mutating remotes automatically
• keep notification sending opt-in
• make risky actions visible as operator decisions

Ecosystem

Brigade is the local operator layer. It integrates with nearby tools instead of trying to absorb all of them.

flowchart TB
    BRIGADE["Brigade<br/>local operator layer"]

    subgraph MEMORY [" memory and handoffs "]
        OPENCLAW["OpenClaw"]
        HERMES["Hermes"]
        MDOCTOR["memory-doctor"]
        BDOCTOR["bootstrap-doctor"]
    end

    subgraph SAFETY [" safety and operations "]
        GUARD["Content Guard"]
        PANTRY["Agent Pantry"]
        NOTIFY["agent-notify"]
        TOKEN["tokenjuice"]
    end

    subgraph NATIVE [" native Brigade stations "]
        REPOS["repo fleet"]
        TOOLS["tool catalog"]
        SECURITY["security scan"]
        HANDOFFS["handoff promotion"]
    end

    BRIGADE --> MEMORY
    BRIGADE --> SAFETY
    BRIGADE --> NATIVE

    classDef core fill:#2563eb,stroke:#1d4ed8,color:#fff;
    classDef group fill:#f8fafc,stroke:#94a3b8,color:#334155;
    class BRIGADE core;
    class OPENCLAW,HERMES,MDOCTOR,BDOCTOR,GUARD,PANTRY,NOTIFY,TOKEN,REPOS,TOOLS,SECURITY,HANDOFFS group;

Memory and handoff tools:

• OpenClaw: personal AI assistant and memory owner.
• Hermes: local memory owner and handoff writer convention.
• memory-doctor: focused maintenance CLI for Claude Code / OpenClaw memory.
• bootstrap-doctor: audits and trims oversized OpenClaw bootstrap files.

Safety and operations tools:

• Content Guard: policy-driven content scanning and publish checks.
• Agent Pantry: encrypted browser session, cookie, and secret sync for agent machines.
• agent-notify: optional notification hooks for long-running agent work.
• tokenjuice: output compaction for terminal-heavy agent workflows.

Brigade also has native local workflows for repo fleet operations, portable tool catalogs, security scans, and handoff promotion. The highlights are below.

Repo Fleet

brigade repos watches a configured set of local repositories and turns their state into reviewable evidence: health scans, sweeps, reports, fleet actions, and release trains.

flowchart LR
    CONFIG[".brigade/repos.toml<br/>configured local repos"]
    SCAN["repos scan / sweep<br/>safe metadata only"]
    REPORT["fleet report<br/>health evidence"]
    ACTIONS["reviewed actions<br/>start · done · defer"]
    RELEASE["release train<br/>manual checklist"]

    CONFIG --> SCAN --> REPORT --> ACTIONS --> RELEASE
    RELEASE -. no publish step .-> MANUAL["operator publishes manually"]

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class CONFIG,SCAN,REPORT local;
    class ACTIONS,RELEASE,MANUAL review;

• Repos live in a gitignored .brigade/repos.toml. Nothing is cloned, pushed, or mutated remotely.
• brigade repos scan and brigade repos sweep collect local health evidence.
• Reports become fleet actions you start, finish, defer, or dispatch by hand.
• Release trains gather readiness evidence and checklists without publishing anything.

Full command list in Repo fleet.

Tool Catalog

brigade tools describes local callable tools, slash commands, skills, scripts, and MCP configs across harnesses, then gates execution behind an approval queue. brigade tools defaults refreshes built-in portable tool entries while preserving custom repo tools.

flowchart LR
    SOURCE["tools/<br/>tracked portable sources"]
    CATALOG[".brigade/tools.toml<br/>catalog"]
    PROJECT["sync-tools<br/>harness projections"]
    APPROVAL["call plan / queue<br/>operator approval"]
    RUN["run receipt<br/>logs · replay · checkpoints"]

    SOURCE --> CATALOG --> PROJECT
    CATALOG --> APPROVAL --> RUN
    PROJECT -. local generated .-> HARNESSES[".codex · .claude<br/>.opencode · .antigravity · .pi · .cursor<br/>.aider · .goose · .continue · .copilot<br/>.qwen · .kimi · .adal · .openhands · .mcp"]

    classDef source fill:#ecfdf5,stroke:#059669,color:#064e3b;
    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class SOURCE source;
    class CATALOG,PROJECT,HARNESSES local;
    class APPROVAL,RUN gate;

• Discovery is read-only: list, search, describe, contracts.
• Projections write reviewed harness-specific tool docs. There is no auto-sync.
• Script calls move through plan, queue, approve, run, with run receipts and replay.
• Runtimes are supervised explicitly. Brigade never auto-starts MCP servers or stores auth.

Details in Tool catalog.

Handoff Promotion

Reviewed scanner imports can be promoted into memory handoff drafts instead of being retyped by hand.

flowchart LR
    IMPORT["work import<br/>decision · finding · command · incident"]
    PLAN["plan-handoff<br/>preview target & blockers"]
    PROMOTE["promote-handoff<br/>write draft"]
    LINT["handoff lint<br/>format · route · guard"]
    DRAFT["memory-handoffs/<br/>reviewed draft"]
    OWNER["memory owner ingest<br/>outside Brigade"]

    IMPORT --> PLAN --> PROMOTE --> LINT --> DRAFT --> OWNER
    LINT -->|blocked| REPAIR["repair import"]

    classDef import fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef gate fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class IMPORT,PLAN,PROMOTE import;
    class LINT,REPAIR gate;
    class DRAFT,OWNER memory;

• Works for durable non-task imports: decisions, preferences, links, commands, findings, incidents.
• brigade work import plan-handoff previews the target and blockers, promote-handoff writes the draft and lints it.
• Drafts land in the normal handoff inbox. Canonical memory is never edited directly.
• Raw private chat fields are rejected and secret-looking values are redacted before the draft is written.

See Handoff promotion.

Deep Research

brigade research turns a research question into a local report and a reviewed Memory Handoff. Trusted local files and configured CLI lanes are used first; browser or web sources are opt-in with --web and labeled as untrusted source material.

flowchart LR
    QUESTION["research question"]
    RUN["research run<br/>local-first · resumable"]
    REPORT["report.html<br/>report.md"]
    EXPORT["export-handoff<br/>explicit writer inbox"]
    DRAFT["memory-handoffs/<br/>linted draft"]
    MEMORY["memory owner ingest<br/>cards or learnings"]

    QUESTION --> RUN --> REPORT
    RUN --> EXPORT --> DRAFT --> MEMORY
    EXPORT -. drift visible .-> REVIEW["work brief<br/>center reviews<br/>release evidence"]

    classDef local fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    classDef memory fill:#ecfdf5,stroke:#059669,color:#064e3b;
    class QUESTION,RUN,REPORT local;
    class EXPORT,REVIEW review;
    class DRAFT,MEMORY memory;

brigade research run "what should we remember about this topic?" --corpus docs
brigade research export-handoff <run-id> --inbox codex
brigade research handoffs doctor
brigade research handoffs import-issues
brigade research show <run-id>

Exports are explicit and receipt-backed. Brigade records the source fingerprint for the handoff artifact, then warns when a completed research run has no export, a missing export path, or a stale export after the run artifact changes. The doctor is read-only; import routing creates reviewable work inbox items instead of exporting or ingesting memory automatically.

Agent Pantry

The pantry station (alias larder) wires Agent Pantry into the same operator workflow: encrypted browser session, cookie, and secret sync between agent machines. The pantry is where the chef stores the cookies and the secret recipes.

• brigade add pantry installs agentpantry.
• brigade pantry status gives a pantry-specific health readout.
• brigade pantry setup plan --role source|sink previews or writes a reviewed setup plan.
• Pantry checks are advisory. An unwired install warns but never fails a workspace run.

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
• install schedulers
• push to GitHub
• publish packages
• send notifications by default
• save every note automatically
• turn memory ingest into a silent background process
• skip review for ambiguous, risky, or failed notes

That pause is the point. Agent memory should be useful, not noisy.

For OpenClaw Users

OpenClaw can be the memory owner. Brigade gives nearby tools a way to contribute checked handoffs back into that owner memory without forcing every tool to know OpenClaw internals.

flowchart LR
    WRITERS["Codex · Claude · OpenCode<br/>Antigravity · Pi · Cursor writer inboxes"]
    BRIGADE["Brigade<br/>draft · lint · source coverage"]
    OPENCLAW["OpenClaw<br/>memory owner"]
    MEMORY["canonical memory"]
    RECEIPTS["ingest receipts<br/>promoted · skipped · failed"]

    WRITERS --> BRIGADE --> OPENCLAW --> MEMORY
    OPENCLAW --> RECEIPTS --> BRIGADE

    classDef brigade fill:#2563eb,stroke:#1d4ed8,color:#fff;
    classDef owner fill:#ef4444,stroke:#b91c1c,color:#fff;
    classDef local fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    class BRIGADE brigade;
    class OPENCLAW owner;
    class WRITERS,MEMORY,RECEIPTS local;

A repo-adjacent setup is:

brigade init --target ./my-repo --depth repo --harnesses openclaw,codex,claude,opencode,antigravity,pi,cursor,aider,goose,continue,copilot,qwen,kimi,adal,openhands
brigade handoff sources init --target ./my-repo
brigade handoff doctor --target ./my-repo

An OpenClaw workspace setup does not need to be inside a code repo:

brigade init --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
brigade handoff sources init --target ~/agent-workspace
brigade handoff doctor --target ~/agent-workspace

Then writer tools leave handoffs in their own inboxes, and the memory owner ingests the safe targeted notes while Brigade keeps receipts for promoted, routed, skipped, failed, malformed, and warning outcomes.

For Hermes Users

Hermes now has a first-class Brigade handoff inbox:

flowchart LR
    HERMES["Hermes"]
    INBOX[".hermes/memory-handoffs/"]
    FRAGMENTS[".brigade/hermes/<br/>adapter fragments"]
    VERIFY["operator verify-harness"]
    HANDOFFS["handoff list / lint"]

    HERMES --> INBOX
    HERMES --> FRAGMENTS
    INBOX --> VERIFY
    FRAGMENTS --> VERIFY
    VERIFY --> HANDOFFS

    classDef hermes fill:#7c3aed,stroke:#5b21b6,color:#fff;
    classDef local fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    class HERMES hermes;
    class INBOX,FRAGMENTS,VERIFY,HANDOFFS local;

brigade init --target . --depth workspace --harnesses hermes
brigade handoff sources init --target . --force

brigade handoff draft --target . --inbox hermes \
  --title "Hermes note" \
  --summary "Hermes can write a local Brigade handoff." \
  --content "### Hermes note

Durable context goes here."

Check the local wiring with:

brigade operator verify-harness --harness hermes --target .
brigade handoff list --target .

The verifier checks both the .hermes/memory-handoffs/ writer inbox and the .brigade/hermes/ adapter fragments.

See Hermes handoffs for the current boundaries.

Content Guard

Brigade handles the memory and operator workflow. Content Guard checks whether content is safe to publish or save.

flowchart LR
    SCAN["security scan<br/>redacted findings"]
    BUNDLE[".brigade/security/latest<br/>JSON · Markdown · SARIF"]
    REVIEW["review / suppress<br/>accepted risk with reason"]
    IMPORT["work import<br/>security follow-up"]
    RELEASE["release readiness<br/>local blocker evidence"]

    SCAN --> BUNDLE --> REVIEW
    BUNDLE --> IMPORT
    REVIEW --> RELEASE
    IMPORT --> RELEASE

    classDef scan fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    classDef local fill:#f1f5f9,stroke:#94a3b8,color:#334155;
    classDef review fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
    class SCAN scan;
    class BUNDLE,IMPORT,RELEASE local;
    class REVIEW review;

Use it at three points:

• before memory ingest: brigade handoff lint --content-guard
• before publishing: brigade scrub --policy public-repo
• after findings appear: brigade work import content-guard

Policy names are intentionally plain:

• personal: local/internal working notes
• public-repo: code and docs before push
• public-content: stricter checks for blog, social, and site copy

brigade operator doctor and brigade operator status show whether Content Guard is installed, which policy is expected, which pre-push hook is active, and the latest local scan summary when available.

Brigade also ships a read-only local security scanner. brigade security scan produces redacted findings you can review, suppress with a reason, or import into the work inbox. See Security and Content Guard.

Where The Detailed Docs Went

The full technical walkthrough still exists; it is just not the README anymore.

• Technical guide: the detailed command walkthrough.
• Security and Content Guard: scanner policies, handoff guards, and import flow.
• Handoff promotion: how notes move toward memory.
• OpenClaw memory ingest checklist: the ingest boundary and receipt checks for handoffs.
• Hermes handoffs: Hermes writer inbox setup.
• Repo fleet: local multi-repo health, actions, and release evidence.
• Tool catalog: portable tools, projections, approvals, and run receipts.
• Internal dogfood loop: how this repo uses Brigade on itself.
• Command inventory: every public CLI command.
• Roadmap: current direction.
• Roadmap archive: completed or intentionally closed roadmap items.

Tiny Glossary

• Harness: an agent tool such as OpenClaw, Hermes, Codex, Claude Code, OpenCode, Antigravity, Pi, or Cursor.
• Handoff: a note an agent writes for later review.
• Inbox: the local folder where handoff notes wait.
• Memory owner: the place that keeps durable shared memory.
• Operator: the human deciding what gets saved, run, or published.