Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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-write or danger-full-access) sets the native Codex sandbox. --sandbox overrides it for one run. --read-only also 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 --worktree runs are exempt. --allow-dirty is 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.lock stops two runs from changing the same checkout. Locks from dead processes are replaced.
  • Detached checkout. --worktree runs agents in a detached checkout under ~/.cache/brigade/worktrees/, writes the diff to changes.patch, removes the checkout and leaves yours untouched. It cannot be combined with --no-artifacts.

Common flags

  • --dry-run prints the planned assignments as JSON and stops.
  • --show-plan and --verbose print the plan, worker statuses and synthesis status.
  • --cwd sets the working directory for agent CLI calls, and --roster picks a roster file.
  • --handoff writes a handoff for a successful run, and --handoff-inbox sets where it goes.
  • --inspect prints the same summary as brigadestack runs show.
  • --output-dir picks the artifact directory, and --no-artifacts skips artifacts.