Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

Docs / Reference

run

Send one task to a planned set of agents and read back a single answer.

Reach for run when you want a task split across agents from different vendors and the results merged into one answer.

brigadestack run "<task>" is the bounded orchestrator path. One orchestrator plans the work, BrigadeStack 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. Plans can stage assignments so dependent workers receive earlier-stage results while same-stage workers still run in parallel.

The useful trick is cost and context control: use the best reasoning model for the orchestrator work, then send the long implementation pass to Codex. A Fable orchestrator can plan the task and synthesize the result while Codex burns the execution tokens on edits, tests, and changes.patch.

brigadestack run "review this repo and suggest the next implementation step"
brigadestack run "plan the migration" --dry-run
brigadestack run "review this repo" --show-plan
brigadestack run "review this repo" --verbose
brigadestack run "review this repo" --cwd /path/to/repo
brigadestack run "review this repo" --roster /path/to/roster.toml
brigadestack run "review this repo" --handoff
brigadestack run "review this repo" --handoff-inbox .claude/memory-handoffs
brigadestack run "review this repo" --read-only
brigadestack run "review this repo" --read-only --inspect
brigadestack run "make the change" --allow-dirty
brigadestack run "make the change" --worktree
brigadestack run "review this repo" --sandbox workspace-write
brigadestack run "review this repo" --output-dir /tmp/brigade-run

Common brigadestack 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 brigadestack 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.

See Run a task on another agent for roster setup, home roster fallback, per-agent model pins, staged plans, sandbox defaults, dirty-tree guards, run locking, and the detached worktree patch flow.

Run artifacts

run writes artifacts by default under .brigade/runs/<id> below --cwd:

FileContents
run.jsontask, cwd, orchestrator, mode flags, status, artifact path, handoff path, timestamps, and duration
roster.jsoneffective orchestrator, agents, limits, allow-list, and timeouts
plan-attempts.jsonraw planner outputs, parse status, and parse errors from initial/correction attempts
plan.jsonparsed worker assignments, including stage values when present
worker-results.jsonworker status, details, and text output for non-dry runs
synthesis.jsonorchestrator synthesis status, detail, and raw text for non-dry runs
final.txtfinal synthesized answer for non-dry runs
changes.patchdetached --worktree diff artifact when worktree mode is used

Use --output-dir <path> to pick the artifact directory, or --no-artifacts for a throwaway run.

Inspect a completed run without opening each JSON file:

brigadestack runs list --cwd /path/to/repo
brigadestack runs latest --cwd /path/to/repo
brigadestack runs show .brigade/runs/<run-id>