# run, dogfood

## run

`brigade run "<task>"` is the aboyeur path. One orchestrator plans the work, Brigade 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 chef 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
brigade run "review this repo and suggest the next implementation step"
brigade run "plan the migration" --dry-run
brigade run "review this repo" --show-plan
brigade run "review this repo" --verbose
brigade run "review this repo" --cwd /path/to/repo
brigade run "review this repo" --roster /path/to/roster.toml
brigade run "review this repo" --handoff
brigade run "review this repo" --handoff-inbox .claude/memory-handoffs
brigade run "review this repo" --read-only
brigade run "review this repo" --read-only --inspect
brigade run "make the change" --allow-dirty
brigade run "make the change" --worktree
brigade run "review this repo" --sandbox workspace-write
brigade run "review this repo" --output-dir /tmp/brigade-run
```

Common `brigade 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 `brigade 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 [The brigade run](/docs/concepts/the-brigade-run/) 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.

## dogfood

`brigade dogfood` is the shortcut for using Brigade on itself or another trusted repo. It uses a built-in single-agent roster (Codex by default, selectable with `--agent-cli`), read-only prompt policy, normal run artifacts, a default Memory Handoff, and an artifact summary.

Set it up once:

```bash
brigade dogfood init --target /path/to/repo
```

That writes local defaults to `.brigade/dogfood.toml`, which is gitignored because it stores machine-local paths and preferences. New dogfood configs default handoffs to `.codex/memory-handoffs/` because the dogfood roster is Codex-driven. Pass `--handoff-inbox` if your memory owner ingests a different path.

Daily commands:

```bash
brigade dogfood
brigade dogfood status
brigade dogfood next
brigade dogfood --target /path/to/repo
```

- `brigade dogfood` runs the configured daily path from the repo.
- `brigade dogfood "review today's changes"` overrides only the task.
- `brigade dogfood status` checks paths, sandbox mode, CLI availability, ignore rules, and the latest run.
- `brigade dogfood latest` shows the latest configured dogfood run.
- `brigade dogfood next` prints the latest extracted next step.

Dogfood writes `summary.md` beside each run's JSON artifacts when a final answer or next step exists. It defaults to a 600 second per-agent timeout. Dogfood runs use Codex's native read-only sandbox with a prompt-level read-only policy (trusted-workspace execution). Pass `--native-read-only-sandbox` to force explicit native read-only enforcement.

Useful switches:

- `--agent-cli` selects the dogfood agent CLI: codex, claude, opencode, antigravity, pi, cursor, or ollama:<model>. Defaults to codex.
- `--no-handoff` skips the dogfood handoff.
- `--no-inspect` skips the artifact summary.
- `--native-read-only-sandbox` forces explicit native read-only sandbox enforcement. Dogfood already runs a native read-only sandbox by default.

## Run artifacts

CLI runs write artifacts by default under `.brigade/runs/<id>` below `--cwd`; dogfood runs use `.brigade/runs/<id>` below the configured target:

| 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 |
| `summary.md` | dogfood summary with run metadata, final answer, and extracted next step when present |

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
brigade runs list --cwd /path/to/repo
brigade runs latest --cwd /path/to/repo
brigade runs show .brigade/runs/<run-id>
```