Brigade, end to end

Brigade’s own one-liner: "Your agents run loops. Brigade keeps the receipts." It is AI agent memory, handoffs, and local guardrails for Codex, Claude Code, OpenCode, and over a dozen other harnesses. It runs on the machine you control: local by default, loud about the exceptions. Holding both halves of this panel in your head is the whole mental model.

Brigade was hand-rolled one incident at a time around an always-on OpenClaw agent plus daily Codex and Claude Code sessions. Two failures shaped the design more than anything planned. First, a nightly "dreaming" job promoted raw session fragments straight into memory and bloated MEMORY.md past the bootstrap budget; every session then started with truncated memory and nobody noticed for weeks. Blind auto-promotion died that day. Second, 195 handoff notes sat unread across 35 repos because the ingester had a hardcoded three-repo 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 memory loop is the core; everything else orbits it. Writer harnesses leave handoff notes as they work. Brigade lints, guards, and classifies each one, then files the safe, targeted notes into durable memory on its own. A memory owner (OpenClaw, Hermes, or just you) only steps in for the ambiguous few.

1. Agents write handoffsEach writer harness drops a handoff note into its own local inbox (e.g. .claude/memory-handoffs/) as it works.
2. Brigade lints & classifiesBefore a note can become memory, it is parsed, guarded, and classified. Nothing reaches memory unlinted.
3. Safe notes auto-fileNotes that name a valid target and clear every guard file themselves into durable memory automatically.
4. Risky notes waitAnything ambiguous, unsafe, or failed is kicked to a review inbox for the memory owner to decide.
5. Receipts + better contextFuture sessions start with better context, and a plain-file receipt records exactly what happened.

The same five steps as a diagram: writer harnesses hand off, Brigade lints and classifies, safe notes reach durable memory through the owner, the risky few branch to review, and memory feeds the next session.

Brigade borrows the vocabulary of a professional kitchen brigade (a brigade de cuisine). The terms are load-bearing, not decoration: internalize them and the rest of the system reads cleanly. Definitions are verbatim from docs/technical-guide.md.

harnessthe line cook

An AI agent program: Claude Code, Codex, OpenCode, Antigravity, Pi, Cursor, OpenClaw, Hermes, and more.docs/technical-guide.md

operatorthe chef

You, the human running the agents and making the explicit decisions about what gets saved, run, or published.

handoffthe ticket

A memory note an agent writes to be saved long-term, held in its own inbox until linted and classified.

ingest / ingesterexpediting to the pass

Reading handoff notes from every inbox and filing them into permanent memory. Conservative by design.

stationa kitchen station

A subsystem of Brigade (memory, security, tokens, pantry, ...) with its own commands and a health check.

mise en placeeverything in its place

Rules, memory, tools, inboxes, and guards laid out before the session gets expensive. The core idea.

aboyeurthe expediter

The kitchen expediter who calls out orders. In Brigade, the orchestrator behind a cross-model `brigade run`.

receiptthe docket

A local file logging that something happened, kept for audit and proof. Brigade writes them but never acts on them.

gatethe chef’s yes

A manual approval checkpoint; nothing risky happens without your yes.

dogfoodstaff meal

Brigade used on itself or another trusted repo.

The 41KB incident produced the central design decision: memory has two layers. Knowledge cards under memory/cards/ hold the detail; MEMORY.md stays a slim, one-line-per-card index that loads every session and is guarded against the 12KB budget. Brigade never edits canonical memory itself — the owner does the writing.

Brigade is partitioned into nine builtin stations (the _BUILTIN tuple in registry.py). Each is a frozen Station dataclass with a name, a summary, kitchen aliases, an optional doctor() health check, and the managed tools attached to it. The station is the unit of the system.

This is the single most important piece of Brigade. decide() (ingest.py) is the pure function that turns a parsed handoff into one of four outcomes: promoted, routed, inboxed, or skipped. Every branch that cannot prove a note is safe routes it to the review inbox. Conservative by default — that pause is the point.

The same guardrail in code. Notice that every failure path constructs an Outcome("inboxed", ...) instead of writing — the safe default is always review.

def decide(sections, target, promote_cards, route_documents) -> Outcome:
    action = sections.get("recommended memory action", "").strip().lower()

    stray = [s for s in sections if s not in KNOWN_SECTIONS]
    if stray:
        return Outcome("inboxed",
            reason=f"unknown sections present (parser may have split content): {stray}")

    if action in ("create-card", "update-card") and promote_cards:
        card = sections.get("target card", "").strip()
        content = sections.get("suggested card content", "")
        if not SAFE_CARD_NAME_RE.match(card):
            return Outcome("inboxed", reason=f"target card name unsafe: {card!r}")
        if not content.lstrip().startswith("---"):
            return Outcome("inboxed", reason="card content missing YAML frontmatter")
        if scan_untrusted(content).flagged:
            return Outcome("inboxed", reason="injection signal in card content ...")
        return Outcome("promoted", dest=target / "memory" / "cards" / card)

brigade run "<task>" is a bounded cross-model orchestration. The aboyeur (the kitchen expediter) plans the task into staged JSON assignments; workers run in parallel within a stage through their own CLIs; later stages receive earlier results; the orchestrator synthesizes. It is intentionally bounded: two orchestrator calls plus the planned worker calls. No infinite loop.

How "serial across stages, parallel within a stage, later stages see earlier results" is actually implemented.

all_results: list[WorkerResult] = []
stages = sorted({a.stage for a in assignments})
for stage in stages:
    stage_assignments = [a for a in assignments if a.stage == stage]
    prior_results = list(all_results)
    max_workers = min(roster.max_workers, len(stage_assignments))
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        future_to_index = {
            executor.submit(run_one, a, prior_results): i
            for i, a in enumerate(stage_assignments)
        }
        for future in as_completed(future_to_index):
            i = future_to_index[future]
            try:
                stage_results_by_index[i] = future.result()
            except Exception as exc:
                a = stage_assignments[i]
                stage_results_by_index[i] = WorkerResult(
                    worker=a.worker, task=a.task, text="", ok=False, detail=str(exc)[:200])
    all_results.extend(stage_results_by_index[i] for i in range(len(stage_assignments)))

Brigade reaches models with no SDKs and no API keys: it builds subprocess argv for the user’s own authenticated CLIs. Because not every CLI can truly enforce read-only, Brigade is honest about it. hard = a native sandbox the model cannot escape; soft = read-only is only a prompt instruction; none = read_only is not applied at all. A writable --sandbox override downgrades even a hard CLI to prompt-only, with a loud advisory.

8 hard · 7 soft · 2 none. From READ_ONLY_ENFORCEMENT in agents.py. ollama:<model> refs always resolve to "none".

The 17 run-CLI adapters split across three enforcement strengths. Knowing which bucket your CLI falls in tells you how much to trust a read-only run.

The codex adapter is the cleanest example of the "build argv, no shell" pattern. Every external command is an argv list run through proc.run, which captures output and normalizes failure to exit codes.

def _codex_argv(prompt, read_only, sandbox):
    if sandbox:
        return ["codex", "exec", "--sandbox", sandbox, prompt]   # writable override
    if read_only:
        return ["codex", "exec", "--sandbox", "read-only", prompt]  # hard sandbox
    return ["codex", "exec", prompt]

# proc.run: no shell, bounded, failures become exit codes
cp = subprocess.run(args, capture_output=True, text=True,
                    timeout=timeout, check=False, stdin=subprocess.DEVNULL)
# FileNotFoundError -> Result(code=127, ...)   # missing tool, not a raise
# TimeoutExpired    -> Result(code=124, ...)   # hung tool, bounded

brigade init does not run a script of imperative steps. It composes manifests (a depth manifest + one per selected harness + includes), dedupes them by destination so a harness can override a baseline file, renders the templates, and atomically rewrites a marker-delimited block in .gitignore.

# Dedupe files by dst (last-wins): a harness manifest can override a baseline file.
seen: dict[str, dict] = {}
for entry in files:
    seen[entry["dst"]] = entry
deduped_files = list(seen.values())

# Per selected harness, write a managed, marker-delimited gitignore block:
for h in selection.harnesses:
    inbox = WRITER_INBOXES.get(h)
    if inbox:
        lines += [f"{inbox}/*",            # ignore session-local handoffs
                  f"!{inbox}/TEMPLATE.md",  # but keep the template
                  f"!{inbox}/.gitkeep"]

Brigade exposes its skills and memory cards to agents over a zero-dependency, read-only MCP server: a single line-oriented JSON-RPC loop on stdin/stdout that only ever initializes, lists resources, and calls read tools. Managed tools follow the same humility: an absent or unconfigured fleet tool is advisory (WARN/MANUAL), never a hard failure of the workspace doctor.

for line in sys.stdin:
    request = json.loads(line)               # newline-delimited JSON-RPC 2.0
    method = str(request.get("method") or "")
    if method == "initialize":
        _emit(response(id, result={"protocolVersion": "2024-11-05",
            "capabilities": {"resources": {}, "tools": {}}}))
    elif method == "resources/list":
        _emit(response(id, result={"resources": list_resources()}))
    elif method == "tools/call":
        payload, failed = call_tool(name, arguments)   # station-supplied callback
        _emit(response(id, result={"content": [{"type": "text", "text": text}],
                                   "isError": failed}))

Everything above is reachable through one CLI. COMMAND_GROUPS (cli/_common.py) organizes all 38 top-level commands into five families; a test enforces that every command appears in exactly one group, so nothing can be silently un-grouped. This is the map of where each capability lives.

Brigade is the brigade de cuisine itself — the executive chef and the line — but it does not work alone. The stations you saw attach to managed tools (content-guard, agentpantry, code-search, miseledger, and more), each owning one job and handing off cleanly to the next.