Quickstart

This is the shortest path from a fresh install to a baro-opened pull request.

1. Pick a goal that fits the mode

baro has two execution modes — the full pipeline (default) and the surgical fast path (--quick). Pick the one that matches the goal.

Full pipeline — for goals that involve multiple modules, cross-cutting decisions, or could plausibly be done as several parallel stories:

• "Add a CONTRIBUTING.md at the repo root covering dev setup, tests, and PR conventions."
• "Migrate the hardcoded category list in frontend/lib/categories.ts to a backend dictionary table served by a /categories REST endpoint."
• "Remove the legacy LegacyExportButton component and every reference to it."

Quick mode (--quick) — for trivial single-concept goals (typo, rename, version bump, single-file fix). See Quick mode:

• baro --quick "fix the typo in README footer"
• baro --quick "rename getUser to fetchUser across the auth module"
• baro --quick "bump axios to 1.7.x"

Either way, the goal should have a clear acceptance criterion and shouldn't require ambient product judgement the team hasn't already made.

2. Run baro from inside the repo

cd path/to/your/repo
baro "Your goal text here"

Or pass a longer goal from a file:

baro "$(cat GOAL.md)"

3. Watch the run

baro opens a terminal workbench: an explorer with your agents and changed files on the left, a main view that switches between activity, plan, stats, diff and decisions — and an input strip that lets you talk to any running agent mid-run. See The TUI for the full layout.

Before execution, the Architect reads your codebase and states its cross-cutting decisions as ADRs — a few short turns, longer on large goals. The intake then proposes an execution mode (focused / sequential / parallel) with its reasoning and you confirm it — or pre-force one with --mode. Then Story Agents run, parallel where the plan allows, capped at --parallel.

4. When the run ends

If every story passes and you have gh installed and authenticated, the Finalizer opens a pull request automatically. The PR body includes:

• The original goal
• The DAG plan
• A stories table with commit SHAs
• Diff stats
• Wall time + parallel speedup

If gh isn't available, baro pushes the feature branch and tells you the PR creation step was skipped — open it yourself.

5. Common flags

baro --llm openai --parallel 5 --timeout 1200 "Your goal"

• --llm claude|codex|openai|hybrid — pick the backend for every phase (hybrid = Claude plans and reviews, Codex writes). See LLM providers.
• --mode auto|focused|sequential|parallel — accept the intake's proposal (auto, default) or force a shape.
• --parallel N — cap concurrent stories. 0 = unlimited.
• --timeout SECS — optional per-story wall cap. Progress is guarded by idle watchdogs (a silent agent is caught; a working one is never killed), so most runs don't need this.
• --model opus|sonnet|haiku (Claude) or gpt-5.5|gpt-5.4|gpt-5.4-mini|gpt-5.4-nano (OpenAI) — pin a single model for every phase. Per-phase overrides also exist (--architect-model, --planner-model, --story-model, --critic-model, --surgeon-model).
• --intra-level-delay SECS — wait between successive story spawns inside a level so Librarian can broadcast early findings to siblings. Default 10.
• --quick — surgical fast path for trivial goals. Skips the Architect phase, forces a single-story plan, disables Critic and Surgeon. See Quick mode.
• --doctor — run self-diagnostic and exit. See Troubleshooting.

6. When something goes wrong

Run baro --doctor first. Then check the persisted logs at ~/.baro/runs/. The Troubleshooting page walks through the common cases.