# The brigade run `brigade run ""` 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 ```bash brigade roster init brigade roster doctor ``` That writes `.brigade/roster.toml` with a Codex orchestrator, a Codex coder, and an optional Ollama local researcher: ```toml # 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..timeout_seconds` overrides it for one agent. ## Pin models and stage plans `agents..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:` 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: ```bash 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:`. 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`.