The brigade run

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.

This is the token-control pattern. Keep the expensive model on orchestration: planning, routing, and synthesis. Let Codex spend the long context on code edits, tests, and patch capture. In practice, Fable can act as the architect while Codex does the labor and returns receipts.

Plans can include integer stage values. Assignments in the same stage run in parallel, stages run from lowest to highest, and later-stage workers receive earlier-stage results in their prompt. Plans without stage still run as one parallel stage.

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:

# Brigade aboyeur roster.
# Edit agent roles and CLI refs to match the tools installed on this machine.

orchestrator = "chef"

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

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

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

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

# Cross-model example: pin a model per agent with `model = ...`
# (claude, codex, grok, opencode, pi, kimi, cursor, antigravity).
# Fable 5 plans and synthesizes, GPT 5.5 executes, the handoff records the run.
# Use a model id your CLI account supports (ChatGPT-account codex takes "gpt-5.5").
#
# orchestrator = "architect"
#
# [agents.architect]
# cli = "claude"
# model = "claude-fable-5"
# role = "Plan the work, choose useful workers, and synthesize the final answer."
#
# [agents.builder]
# cli = "codex"
# model = "gpt-5.5"
# role = "Make precise code changes and report what changed."

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.

Pin models and stage plans

agents.<name>.model pins the model a CLI agent runs instead of relying on that CLI’s global default. Pinning is supported on the claude, codex, grok, opencode, pi, kimi, cursor, and antigravity adapters; Brigade places each CLI’s model flag where that CLI expects it (for example grok -m grok-composer-2.5-fast -p) and records the effective pins in roster.json. ollama:<model> CLI refs already name their model, including cloud models such as ollama:qwen3-coder-next:cloud. brigade roster doctor fails before dispatch when a model = pin is set on an adapter that cannot take one.

Use that with staged plans when one model should design the work and another should execute it. A Fable planner can assign research and implementation to Codex workers, then spend its remaining budget on the final synthesis instead of reading terminal noise. Same-stage workers still run in parallel.

Sandbox and roster defaults

limits.sandbox is optional. When set to read-only, workspace-write, or danger-full-access, it becomes the native Codex sandbox for brigade run. Pass --sandbox {read-only,workspace-write,danger-full-access} to override the roster for one run.

--read-only remains a prompt-level review policy for every adapter. For codex agents it also uses native codex exec --sandbox read-only unless --sandbox overrides that native mode. Combining --read-only --sandbox workspace-write keeps the review-only instruction while allowing a less restrictive native sandbox.

When --roster is omitted, Brigade first reads --cwd/.brigade/roster.toml. If that repo roster is missing, it falls back to Path.home()/.brigade/roster.toml. Passing --roster uses exactly that file.

Checkout safety

Write runs in a git worktree refuse to start on a dirty tree unless --allow-dirty is passed. Dry runs, read-only runs, and --worktree runs are exempt, and Brigade’s own .brigade/ state does not count as user work.

Every run takes a local .brigade/run.lock containing the active PID so two runs do not mutate the same checkout at once. Stale locks from dead processes are replaced automatically.

Use --worktree to run agents in a detached checkout from HEAD under ~/.cache/brigade/worktrees/. Brigade writes the resulting diff to changes.patch in the run artifacts, removes the temporary checkout, and leaves the original checkout unchanged. Because the patch is the durable output, --worktree cannot be combined with --no-artifacts.

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" --roster /path/to/roster.toml
brigade run "review this repo" --handoff
brigade run "review this repo" --handoff-inbox .claude/memory-handoffs
brigade run "review this repo" --read-only
brigade run "review this repo" --read-only --inspect
brigade run "make the change" --allow-dirty
brigade run "make the change" --worktree
brigade run "review this repo" --sandbox workspace-write
brigade run "review this repo" --output-dir /tmp/brigade-run

Common brigade run flags

--dry-run prints planned assignments as JSON and stops before worker dispatch.
--allow-dirty bypasses the default dirty-git-worktree guard for write runs.
--worktree runs agents in a detached git worktree and captures changes.patch.
--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.
--roster selects a roster file instead of the repo or home default.
--handoff writes a Memory Handoff for a successful non-dry run.
--handoff-inbox sets the handoff destination.
--inspect prints the same artifact summary as brigade runs show.
--read-only tells the orchestrator and workers to inspect and recommend only.
--sandbox {read-only,workspace-write,danger-full-access} overrides the native Codex sandbox mode from the roster.
--output-dir picks the artifact directory.
--no-artifacts skips artifact writes, except it cannot be combined with --worktree.

The cli values are adapters for installed command-line tools: codex, claude, opencode, antigravity, pi, cursor, aider, goose, continue, copilot, qwen, kimi, adal, openhands, grok, amp, crush, 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.

Search Brigade