# run

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`.

```bash
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](/docs/concepts/bounded-runs) 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:

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