Running baro

Every run starts the same way: a goal, in a git repo.

cd your-repo
baro "Add JWT authentication with role-based access control"

That opens the TUI. Everything else on this page is about running baro when you're not watching it.

Goals from files

Real goals are longer than a shell argument wants to be. Write the goal in a file and pass it directly:

baro --goal-file goal.txt

--goal-file and a positional goal are mutually exclusive. A good goal file names the files and behaviors it's about, states the constraints, and says what proves the work — the more evidence in the goal, the tighter the Architect's contract.

Background runs

--detach starts the run in the background and prints a run id immediately:

baro --headless --detach --goal-file goal.txt
# → run-27112

The run survives the terminal closing. Follow it from any terminal:

baro watch run-27112             # milestone events: phases, merges, verdict
baro logs run-27112 --follow     # the raw event log
baro runs                        # every live run, with pid and repo
baro stop run-27112              # stop one cleanly

Logs persist under ~/.baro/logs/<run-id>.log, so baro logs works after the run ends too.

Headless

--headless runs without the TUI: the plan is auto-confirmed and orchestrator events stream to stdout as JSON — for CI, scripts, and driving baro with a coding agent. It requires a goal (positional or --goal-file). Add --confirm-mode if you want headless runs to emit the proposed execution mode and wait (≤120 s) for a confirmation command before planning continues.

Resume vs continue

Two different verbs for two different situations — the distinction matters:

--resume never re-plans. --continue always re-plans.

baro --resume       # pick an interrupted run back up from prd.json
baro --continue     # follow-up work on the current branch

• --resume is for a run that was interrupted — a stop, a crash, a battery death. baro re-reads prd.json, keeps every settled story exactly as it landed (merge status and commits are preserved on disk), and carries on from where the run stopped. The resume guard makes re-planning structurally impossible on this path: if the plan can't be resumed as-is, the run ends loudly instead of silently starting over. A goal fingerprint ties the resume to the original goal text.
• --continue is for new work on an existing branch — a follow-up, a review fix. Prior work on the branch is re-read as context, planning runs again, and the follow-up lands on the existing PR.

Isolation and budgets

--local-only              # no pushes, no PRs — run against a remote-free clone
--shell-budget <seconds>  # per-command time budget for story shell tools
--timeout <seconds>       # optional per-story wall cap (idle watchdogs already
                          # catch silent agents; a working agent is never killed)
--parallel N              # cap concurrent story agents (0 = unlimited)

--local-only is the hard-isolation switch: baro never pushes, never opens a PR, and the work stays on a local branch you inspect yourself.

Everything else

• Execution shape (focused / sequential / parallel) — Execution modes
• The surgical fast path — Quick mode
• Backends, models, per-phase routing — LLM providers
• What actually guards the work — Verification & gates
• baro --doctor and failed runs — Troubleshooting