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 TUI with three tabs:

• Dashboard — live list of stories, their statuses, and a log panel
• DAG — the dependency graph the planner produced
• Stats — wall time, parallel speedup, token usage, file counts

Pre-execution, the Architect phase (one Opus call, ~30-90s) reads your codebase and decides cross-cutting design points. Then the planner decomposes the goal into stories. Then Story Agents run in parallel, capped at --parallel (default unlimited).

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|openai — pick the provider for every phase. claude (default) shells out to Claude Code; openai calls the OpenAI Responses API natively through Mozaik. See LLM providers.
• --parallel N — cap concurrent stories. Default 0 (unlimited).
• --timeout SECS — per-story timeout. Default 600.
• --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.