baro — Docs

How to diagnose a failed baro run — start with `baro --doctor`, then check the persisted log files.

Most baro runs that fail before any agent starts fail for a small handful of reasons. This page walks you through finding which one you hit and what to do about it.

Start with `baro --doctor`

Whenever a run errors out and you're not sure why, run the built-in self-diagnostic first:

baro --doctor

It runs five fast checks in sequence:

claude is on PATH — the Claude Code CLI is installed and resolvable from your shell.
claude --version returns — the binary actually executes without hanging.
claude --print succeeds on a trivial prompt — Claude is authenticated and your subscription is active. This is the check that catches the most common failure mode.
gh is on PATH — optional but recommended for automatic PR creation by the Finalizer.
~/.baro/runs/ is writable — audit logs and per-call stdout/stderr files land here.

Every passing check prints ✓. Every failing check prints ✗ with a specific remediation hint. Exit code 0 if all pass, 1 if anything fails.

Common failure (`--llm claude`): empty error, exit code 1

The most common report on the Claude path (and what GitHub issue #17 was) is the planner exiting like this:

┌ Claude ─────────────┐
│                                  │
│ ✖ Planning failed                │
│                                  │
│ Claude exited with code 1:       │
│                                  │
└──────────────────────────────────┘

Nothing after the colon. No clue why. Almost always this means Claude Code itself isn't authenticated: claude --print was invoked, refused to respond, and exited 1 with empty stderr.

Fix sequence:

Run claude once with no arguments. It will open a browser login flow if you're not authenticated.
After login, run claude --print -p "say hi" --output-format json. If you get back a JSON envelope with a result, your CLI is good.
Run baro --doctor. The third check (claude --print authenticated call) should now pass.
Re-run baro.

If baro --doctor still fails on that check after claude login, your Claude Code subscription may not be active, or you may be running into a rate limit — verify at claude.com/code.

Reading the log files

Every Claude invocation baro makes for planning or design is persisted to disk before the error is shown. baro 0.25.1 and later prints the log path under the error box:

 full log: /Users/you/.baro/runs/planner-1778512345.log
 diagnose: baro --doctor
 docs:     https://docs.baro.rs/docs/troubleshooting

The log file contains the full stdout and stderr from the Claude CLI subprocess, even when the in-TUI excerpt is empty. Open it directly:

cat ~/.baro/runs/planner-*.log | tail -50

The filename convention:

planner-<unix-secs>.log — the planner phase
architect-<unix-secs>.log — the Architect design phase (baro 0.25+)
refine-<unix-secs>.log — the interactive refine call on the review screen
<project>-<unix-secs>.jsonl and .stderr.txt — the orchestrator audit stream (one per real run)

Permission errors on `~/.baro/`

If baro --doctor reports that the audit dir is not writable, the most common cause is that you installed baro at some point with sudo, which left ~/.baro/ and its contents owned by root.

Fix it:

sudo chown -R $(id -u):$(id -g) ~/.baro

After that, every part of baro that wants to write to ~/.baro/runs/ (audit log, planner log, stderr sidecar) will be able to.

`claude` not on PATH

If baro --doctor reports claude is missing from PATH:

Install Claude Code from claude.com/code if you haven't already.
If you have it installed, your shell may not have it in $PATH. Check which claude. The Claude Code installer typically puts the binary in ~/.local/bin — if ~/.local/bin isn't in your $PATH, add it to your shell profile.
Open a fresh terminal session after installing or modifying $PATH. baro inherits the environment of the shell that launched it.

`--llm openai`: "OPENAI_API_KEY is not set"

If you ran with --llm openai and the planner exits before any story starts with:

planner exited with code 2: [run-planner] --llm openai requires OPENAI_API_KEY to be set

baro couldn't find a key anywhere. Three fixes, in order of preference:

Export the key in your shell so baro inherits it via the subprocess env:
```
export OPENAI_API_KEY=sk-...
baro --llm openai "Your goal"
```
Type the key on the welcome screen. Run baro --llm openai without a CLI goal — baro routes you through a provider picker and an API-key entry screen. Whatever you type stays in baro's memory for the run and is not written to disk.
Check the env after CLI invocations. baro 0.38+ reads OPENAI_API_KEY from the environment even when you pass the goal directly on the command line. If you set the key in .zshrc / .bashrc but a different terminal session is missing it, open a fresh terminal.

If you ran with --llm claude, you do not need OPENAI_API_KEY at all — every phase routes through Claude Code instead.

The Finalizer participant uses GitHub CLI (gh) to open a pull request when a run finishes. If gh isn't installed, baro will still run; it will push the branch and tell you the PR creation step was skipped.

To enable automatic PR creation:

# macOS
brew install gh

# everything else: https://cli.github.com

Then gh auth login once. baro inherits the auth.

Still stuck?

Open an issue at github.com/jigjoy-ai/baro/issues and include:

The output of baro --doctor
The contents of the most recent ~/.baro/runs/planner-*.log (the file path is shown under the error box)
Your baro version (baro --version) and Claude Code version (claude --version)

Troubleshooting