Docs / Checked work
Run a task on another agent
Ask a different vendor's agent to do a task or give a second opinion, and get the result back with a record of what ran.
If you work in a single-vendor tool, you cannot ask another vendor’s agent for help. brigadestack run "<task>" can. Ask Codex to build what Claude planned, or ask a second model to review a change, and the result comes back to you with a record of who did what. BrigadeStack shells out to each agent tool’s own CLI, so it keeps no provider keys.
brigadestack run "review this repo and suggest the next step" --read-only
brigadestack run "plan the migration" --dry-run
--dry-run prints the plan and stops. --read-only tells every agent to inspect and recommend only.
How a run works
One orchestrator plans the work, assigned workers execute through their own CLIs, then the orchestrator writes the final answer. That is two orchestrator calls plus the worker calls in the plan. Keep the expensive model on planning and synthesis, and let a cheaper one spend long context on edits and tests.
Plans can give assignments an integer stage. Same-stage assignments run in parallel, stages run lowest to highest, and later workers see earlier results. Without stage, everything runs as one parallel stage.
Choose which agent runs each role
The roster is the file that says which agent runs each role.
brigadestack roster init
brigadestack roster doctor
roster init writes .brigade/roster.toml with a Codex orchestrator, a Codex coder and an optional Ollama researcher. Agent names are arbitrary, and the orchestrator key picks the agent that plans. Files that name that agent chef still work. The core of the file:
orchestrator = "orchestrator"
[agents.orchestrator]
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."
[limits]
max_workers = 4
timeout_seconds = 600
allow_models = ["codex", "ollama:*"]
The generated file also carries a local Ollama agent and commented examples for pinning models. Ollama models are never pulled for you, so run ollama pull first.
limits.timeout_seconds is the default per-agent timeout, and agents.<name>.timeout_seconds overrides it for one agent. roster init refuses to write when ~/.brigade/roster.toml already applies, because the starter would hide it. With no --roster, BrigadeStack reads .brigade/roster.toml in --cwd. In a linked git worktree it then tries the same file in the parent clone, and last it falls back to ~/.brigade/roster.toml.
The cli values are adapters for installed tools: codex, claude, opencode, antigravity, pi, cursor, aider, goose, continue, copilot, qwen, kimi, adal, openhands, grok, amp, crush, and ollama:<model>. brigadestack roster doctor checks the syntax and which CLIs are on PATH.
Check readiness
brigadestack roster ready inspects a worker pool without dispatching anything. Name agents with --worker, and optionally set --concurrency, --route {brigade,t3}, --isolation {shared,worktree} and --capability:
brigadestack roster ready --worker coder --worker local_researcher --concurrency 2 --json
It reports ready (exit 0), blocked (exit 2) or unverified (exit 3). The evidence lines are the health checks for each selected seat (declaration, executable identity, authentication and entitlement, transport liveness, version gates, model reachability and isolation compatibility), then four checks for the operation: route support, isolation, admission and capacity. A fresh roster usually comes back unverified. Treat it as a list of what to check.
Pin models
agents.<name>.model pins the model a CLI agent runs, on the claude, codex, grok, opencode, pi, kimi, cursor and antigravity adapters. Use it with staged plans when one model should design the work and another should build it. brigadestack roster doctor fails before dispatch if a pin is set on an adapter that cannot take one.
Limits and policy
- Sandbox.
limits.sandbox(read-only,workspace-writeordanger-full-access) sets the native Codex sandbox.--sandboxoverrides it for one run.--read-onlyalso adds a prompt-level review-only instruction for every adapter. - Dirty tree. A write run in a git worktree refuses to start on a dirty tree unless you pass
--allow-dirty. Dry runs, read-only runs and--worktreeruns are exempt.--allow-dirtyis itself refused in a primary checkout that has uncommitted changes, because BrigadeStack would attribute that earlier work to the worker. Commit or stash, run from a linked git worktree, or pass--worktree. - One run at a time. A local
.brigade/run.lockstops two runs from changing the same checkout. Locks from dead processes are replaced. - Detached checkout.
--worktreeruns agents in a detached checkout under~/.cache/brigade/worktrees/, writes the diff tochanges.patch, removes the checkout and leaves yours untouched. It cannot be combined with--no-artifacts.
Common flags
--dry-runprints the planned assignments as JSON and stops.--show-planand--verboseprint the plan, worker statuses and synthesis status.--cwdsets the working directory for agent CLI calls, and--rosterpicks a roster file.--handoffwrites a handoff for a successful run, and--handoff-inboxsets where it goes.--inspectprints the same summary asbrigadestack runs show.--output-dirpicks the artifact directory, and--no-artifactsskips artifacts.