Common Issues

Solutions to frequently encountered problems.

Agent CLI Not Found

Symptom: Error that the agent CLI (Claude, Codex, OpenCode, Cursor, or Gemini) is not found.

Error: Claude CLI not found in PATH. Install it or set agent.cliPath in .chief/config.yaml

or

Error: Codex CLI not found in PATH. Install it or set agent.cliPath in .chief/config.yaml

or

Error: OpenCode CLI not found in PATH. Install it or set agent.cliPath in .chief/config.yaml

Cause: The chosen agent CLI isn't installed or isn't in your PATH.

Solution:

• Claude (default): Install Claude Code CLI, then verify:

  claude --version

• Codex: Install Codex CLI and ensure codex is in PATH, or set the path in config:

  agent:
    provider: codex
    cliPath: /usr/local/bin/codex

  Verify with codex --version (or your cliPath).
• OpenCode: Install OpenCode CLI and ensure opencode is in PATH, or set the path in config:

  agent:
    provider: opencode
    cliPath: /usr/local/bin/opencode

  Verify with opencode --version (or your cliPath).
• Cursor: Install Cursor CLI and ensure agent is in PATH, or set the path in config:

  agent:
    provider: cursor
    cliPath: /path/to/agent

  Run agent login. Verify with agent --version (or your cliPath).
• Gemini: Install Gemini CLI and ensure gemini is in PATH, or set the path in config:

  agent:
    provider: gemini
    cliPath: /path/to/gemini

  Verify with gemini --version (or your cliPath).

Permission Denied

Symptom: The agent keeps asking for permission, disrupting autonomous flow.

Cause: Some agents (like Claude Code) require explicit permission for file writes and command execution.

Solution:

Chief automatically configures the agent for autonomous operation by disabling permission prompts. If you're still seeing permission issues, ensure you're running Chief (not the agent directly) and that your agent CLI is up to date.

Agent Crashes / Retrying

Symptom: The TUI shows 🔄 <agent> crashed, retrying (1/3)....

Cause: The agent process exited with an error.

Solution:

The last few lines of the crashed process's stderr are now shown inline under the retry message in the TUI, so you can usually see the cause without leaving Chief. For example, running Chief as root in Docker surfaces:

🔄 Claude crashed, retrying (1/3)...
   │ --dangerously-skip-permissions cannot be used with root/sudo privileges...

For the complete output, check the agent log. Each run writes its own timestamped file named after your agent — claude-<timestamp>.log (or codex-, opencode-, cursor-, gemini-). Glob for the newest one:

tail -100 .chief/prds/your-prd/claude-*.log

Rate Limit Reached

Symptom: The activity line reads Rate limit reached (5h window) — waiting until 20:00 (1h 33m) and the run sits still, or the header shows a Limit 90% · 20:00 chip while it is still working.

Cause: Your account's usage window for the agent's model is full (or nearly full). This is not a crash, even though the agent CLI exits the same way one does.

Solution:

Nothing — the run waits the window out and carries on by itself. A rate limit is deliberately not treated as a crash: the crash retries would all be spent within half a minute against a window with hours left on it. Chief reads the reset time the agent reports, sleeps until then (plus a minute for clock skew), and starts the next iteration.

A few things worth knowing:

• The warning comes first. The header chip appears while the window is merely filling up (Limit 90% · 20:00), which is the moment to decide whether to let the run continue, switch to a cheaper model for the review and consolidation phases, or stop for the day.
• Stopping works mid-wait. x ends the run without sitting out the rest of the window; nothing new is started once the window resets.
• Waiting is bounded. After six windows in a single run, Chief stops and reports the limit as an error rather than sleeping on for days.
• --no-retry opts out. It means "don't carry on by yourself", which covers waiting too: a rate-limited run ends immediately, with the limit named in the error.

PRD Not Updating

Symptom: Stories stay incomplete even though the agent seems to finish.

Cause: The agent didn't output the completion signal, or file watching failed.

Solution:

1. Check the agent log for errors (per-run files named after your agent, e.g. claude-<timestamp>.log):

   tail -100 .chief/prds/your-prd/claude-*.log  # or codex-*.log / opencode-*.log / cursor-*.log / gemini-*.log

2. Manually mark story complete if appropriate by editing prd.md:

   **Status:** done

3. Restart Chief to pick up where it left off

Loop Not Progressing

Symptom: Chief runs but doesn't make progress on stories.

Cause: Various—the agent may be stuck, context too large, or PRD unclear.

Solution:

1. Check the agent log for what the agent is doing:

   tail -f .chief/prds/your-prd/claude-*.log  # or codex-*.log / opencode-*.log / cursor-*.log / gemini-*.log

2. Simplify the current story's acceptance criteria

3. Add context to prd.md about the codebase

4. Try restarting Chief:

   # Press 'x' to stop (or Ctrl+C to quit)
   chief  # Launch TUI
   # Press 's' to start the loop

Story Parked for Review

Symptom: A story is marked needs-review (◆) and Chief moved on to other stories.

Cause: The agent attempted the story 5 times without signalling <chief-done/>. Chief parks it so one stuck story doesn't block the rest.

Solution:

1. Check the agent log (per-run files like claude-<timestamp>.log, codex-*.log, opencode-*.log, cursor-*.log, or gemini-*.log) to see why it got stuck.
2. Fix the root cause:
   • Story too complex? Split it into smaller stories
   • Unclear acceptance criteria? Clarify them
   • Blocked by another story? Reorder priorities
3. Reset the story's **Status:** in prd.md (e.g. remove it or set pending) and run Chief again.

Max Iterations Reached

Symptom: Chief stops with "max iterations reached" message.

Cause: The global backstop fired. With per-story retries this is rare — it usually means a lot of stories are each churning without completing.

Solution:

1. Increase the limit:

   chief --max-iterations 200

2. Or investigate why it's taking so many iterations:

   • Story too complex? Split it
   • Stuck in a loop? Check the agent log (claude-*.log, codex-*.log, opencode-*.log, cursor-*.log, or gemini-*.log)
   • Unclear acceptance criteria? Clarify them

"No PRD Found"

Symptom: Error about no PRD being found.

Cause: Missing .chief/prds/ directory or invalid PRD structure.

Solution:

1. Create a PRD:

   chief new

2. Or specify the PRD explicitly:

   chief my-feature

3. Verify structure:

   .chief/
   └── prds/
       └── my-feature/
           └── prd.md

Invalid PRD Format

Symptom: Error parsing prd.md.

Cause: The markdown structure doesn't match what Chief expects.

Solution:

1. Verify your story headings use the correct format:

   ### US-001: Story Title

2. Common issues:

   • Missing colon between ID and title in heading
   • ID doesn't match the required LETTERS-NUMBERS pattern (e.g. US-001, AUTH-3) — headings whose ID isn't in this form are not recognized as stories
   • Unexpected **Status:** value — anything Chief doesn't recognize silently falls back to todo (valid values: done, in-progress, todo, needs-review)

Worktree Setup Failures

Symptom: Worktree creation fails when starting a PRD.

Cause: The branch already exists, the worktree path is in use, git state is corrupted, or worktree.dir points somewhere a worktree can't live.

Solution:

1. Chief automatically handles common cases (reuses valid worktrees, cleans stale ones). If it still fails:

2. Find out where the worktree actually is. Its location comes from the worktree.dir template (Settings → Worktree → Directory), which defaults to .chief/worktrees/{prd} but can put worktrees anywhere — so ask git rather than guessing:

   git worktree list

3. Manually clean up, using the path from that listing. A run keeps the PRD's working files inside its worktree, and c in the picker copies them back before removing it — doing this by hand does not, so if .chief/ is gitignored in your project (where the branch never carried them), save them first:

   # Keep the run's record: its prd.md, progress.md and summaries
   cp <path-from-the-listing>/.chief/prds/<prd-name>/*.md .chief/prds/<prd-name>/
   
   # Remove the worktree
   git worktree remove <path-from-the-listing> --force
   
   # Delete the branch if needed
   git branch -D chief/<prd-name>
   
   # Prune git's worktree tracking
   git worktree prune

4. If the error names worktree.dir, the template resolves to the main checkout itself or to its bare parent directory. Give it a subdirectory — ../{repo}-worktrees/{prd} rather than .. — and try again.

5. Restart Chief and try again

When the setup command is what failed

A worktree.setup that exits non-zero aborts the start, but the worktree itself has already been created and is kept. The error message names the log file — <worktree>/.chief/prds/<prd>/setup-<timestamp>.log, inside the worktree the setup was preparing — which holds the command's full output rather than the few lines the modal has room for.

Fix the script, then re-run it against the existing worktree instead of deleting and recreating everything:

chief worktree setup <prd-name>

If the setup hangs rather than fails — waiting on a lock, a password prompt, or a network that never answers — Chief waits forever by default, which is correct for a setup that is merely slow (a cold npm install). Set worktree.setupTimeoutSeconds (Settings → Worktree) to bound it: the command and the whole process tree it started are killed after that many seconds, and the failure names its log file like any other.

If the setup re-runs when you don't want it to: by default it also runs for a worktree that already exists (a resumed run, or a PRD started again), so a non-idempotent command like createdb fails the second time. Either make it idempotent or set worktree.setupOnReuse: false, which limits setup to freshly created worktrees — the spinner then shows Skipped setup (worktree reused).

Worktree Teardown Failed

Symptom: Cleaning a worktree with c opens a "Teardown Failed" dialog instead of removing it, offering "Remove anyway" and "Keep the worktree".

Cause: The configured worktree.teardown command exited non-zero. Since that command is what disposes of the things git knows nothing about — a per-worktree database, a web-server link, containers — Chief treats its failure as a reason not to remove the directory: deleting the checkout would leave those resources orphaned and invisible.

Solution:

1. Read why it failed. The dialog shows the last lines of the output and the path of the full log, .chief/prds/<prd>/teardown-<timestamp>.log.

2. Choose Keep the worktree, fix the cause (start the container the script talks to, drop the database by hand, correct the script), and retry the teardown on its own — this does not remove the worktree, so it can be repeated until it works:

   chief worktree teardown <prd-name>

   Then clean up with c again.

3. Choose Remove anyway when you have dealt with the outside resources yourself, or there were none. It removes the worktree without running the teardown a second time — a command that just failed would only fail again and trap you in the same dialog.

Make the teardown idempotent: it may well run against a worktree it has already torn down (a retry, or a stale worktree being recreated).

PR Creation Failures

Symptom: Auto-PR creation fails after a PRD completes.

Cause: gh CLI not installed, not authenticated, or network issues.

Solution:

1. Verify gh is installed and authenticated:

   gh auth status

2. If not installed, get it from cli.github.com

3. If not authenticated:

   gh auth login

4. You can also create the PR manually:

   git push -u origin chief/<prd-name>
   gh pr create --title "feat: <prd-name>" --body "..."

5. Auto-PR can be disabled in Settings (,) — push-only mode still works

Push Rejected: Branch Behind Remote

Symptom: A finished run reports Push failed: ... ! [rejected] chief/<name> -> chief/<name> (non-fast-forward) on the completion screen, with a hint that the branch "is behind its remote counterpart".

Cause: origin/chief/<name> has commits the local branch doesn't. The usual routes there are cleaning the local branch after it had already been pushed (so it gets recreated from the default branch), or running the same PRD on a second machine that pushed first.

Nothing is lost when this happens — every story commit is still on the local branch. Only the push was refused.

Solution:

Chief now checks for this before a run starts, so you normally see a "Branch Behind Remote" dialog instead of a failed push hours later. It offers to fast-forward (when the branch has no local commits of its own) or rebase onto origin/<branch> (when it does), and names which one it will do. "Start anyway" runs regardless and the push will still be rejected at the end.

To recover a run that already finished this way:

git fetch origin chief/<prd-name>
git rebase FETCH_HEAD          # or: git merge --ff-only FETCH_HEAD
git push -u origin chief/<prd-name>

If the rebase conflicts, resolve it and git rebase --continue, or git rebase --abort to get back to where you were.

Do not reach for git push --force here: the remote commits are ones your branch doesn't have, so forcing would discard them.

The preflight check needs to reach origin. When it can't — offline, no remote, or a branch the remote has never seen — the run starts normally rather than being blocked. Worktree runs and protected branches (main/master) are skipped, since neither is a branch Chief auto-pushes into an existing remote history.

Orphaned Worktrees

Symptom: The picker shows entries marked [orphaned] or [orphaned worktree].

Cause: A previous Chief session crashed or was terminated without cleaning up its worktree.

Solution:

1. Orphaned worktrees are harmless but take disk space
2. Select the orphaned entry in the picker and press c to clean it up
3. Choose "Remove worktree + delete branch" or "Remove worktree only" as appropriate

Chief automatically prunes git's internal worktree tracking on startup, but does not auto-delete worktree directories to avoid data loss.

Merge Conflicts

Symptom: Merging a completed branch fails with conflict list.

Cause: The PRD's branch has changes that conflict with the target branch.

Solution:

1. Chief shows the list of conflicting files in the merge result dialog
2. Resolve conflicts manually in a terminal:

   cd /path/to/project
   git merge chief/<prd-name>
   # Resolve conflicts in the listed files
   git add .
   git commit

3. Or push the branch and resolve via a pull request on GitHub

Garbled Icons or Unreadable Colors

Symptom: Status/tool icons show as boxes, question marks, or double-width gaps; or text is barely visible (e.g. pale yellow/green on a light terminal).

Cause: Some terminals, multiplexers, or piped-log setups render emoji poorly (mis-measured widths break the layout). Very old or minimal color profiles can also clash with the palette.

Solution:

• Colors adapt to the terminal background automatically. If they still look wrong, strip styling entirely:

  NO_COLOR=1 chief

• Replace emoji/Unicode icons with ASCII fallbacks:

  CHIEF_ASCII=1 chief

See Configuration → Appearance for details.

The Machine Fell Asleep Mid-Run

Symptom: You start a run, walk away, and come back to a loop that made far less progress than the elapsed time suggests — as if it only worked while you were sitting there.

Cause: Nobody touches the keyboard during a run, so the OS counts the machine as idle and puts it to sleep mid-story. The agent is suspended along with it and only picks up again when you wake the machine.

How to confirm: The completion screen adds a line like Mac slept 56m00s during the run whenever it detected a nap. Every duration Chief shows — per-story times, Completed in, the ETA — is working time and stops with the machine, so that line is what accounts for the difference against the clock on the wall. No line means no sleep was detected. The figure isn't saved anywhere: a restarted Chief starts counting again from zero.

Solution:

Chief holds a sleep assertion for the duration of a run, so this shouldn't happen with the default settings. It also warns you before a run starts when it can see the risk up front — on battery, or with loop.keepAwake switched off — with a Mac May Fall Asleep Mid-Run dialog offering Start anyway / Cancel. The dialog asks again on every start, and stays out of the way when the power source can't be determined. If a run still slept through:

• Confirm the setting is on — , → Loop → Keep machine awake, or loop.keepAwake in .chief/config.yaml. It's applied when a loop starts, so toggling it mid-run only takes effect from the next start.
• Verify the assertion is actually held while a loop runs:

  pmset -g assertions | grep caffeinate

  You should see a caffeinate process asserting on behalf of Chief's PID.
• On a MacBook, open the lid. A closed lid with no external display sleeps the machine regardless — no assertion can override that.
• Only the machine is held awake, not the display: a screen that goes dark is expected and doesn't stop the loop.
• Non-macOS platforms: Chief can't hold the assertion yet, so configure this at the OS level (e.g. systemd-inhibit, or your power settings).

See Configuration → loop.keepAwake for the full behavior.

Still Stuck?

If none of these solutions help:

1. Check the FAQ
2. Search GitHub Issues
3. Open a new issue with:
   • Chief version (chief --version)
   • Your prd.md (sanitized)
   • Relevant agent log excerpts (e.g. claude-<timestamp>.log, codex-*.log, opencode-*.log, cursor-*.log, or gemini-*.log)