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-runprints planned assignments as JSON and stops before worker dispatch.--allow-dirtybypasses the default dirty-git-worktree guard for write runs.--worktreeruns agents in a detached git worktree and captureschanges.patch.--show-planprints assignments before a normal run.--verboseprints the plan, worker statuses, and synthesis status.--cwdsets the working directory for agent CLI calls.--rosterselects a roster file instead of the repo or home default.--handoffwrites a Memory Handoff for a successful non-dry run.--handoff-inboxsets the handoff destination.--inspectprints the same artifact summary asbrigadestack runs show.--read-onlytells 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-dirpicks the artifact directory.--no-artifactsskips 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:
| File | Contents |
|---|---|
run.json | task, cwd, orchestrator, mode flags, status, artifact path, handoff path, timestamps, and duration |
roster.json | effective orchestrator, agents, limits, allow-list, and timeouts |
plan-attempts.json | raw planner outputs, parse status, and parse errors from initial/correction attempts |
plan.json | parsed worker assignments, including stage values when present |
worker-results.json | worker status, details, and text output for non-dry runs |
synthesis.json | orchestrator synthesis status, detail, and raw text for non-dry runs |
final.txt | final synthesized answer for non-dry runs |
changes.patch | detached --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>