FAQ

Frequently asked questions about Chief.

General

What is Chief?

Chief is an autonomous PRD agent. You write a Product Requirements Document with user stories, run Chief, and watch as your code gets built—story by story.

Why "Chief"?

Named after Chief Wiggum from The Simpsons (Ralph Wiggum's dad). Chief orchestrates the Ralph loop.

Is Chief free?

Chief itself is open source and free. However, it requires an agent CLI with its own access:

• Claude Code (default) — requires a Claude Pro subscription or Anthropic API access
• Codex CLI — requires an OpenAI API key
• OpenCode CLI — supports multiple model providers
• Cursor CLI — requires a Cursor account
• Gemini CLI — requires Google/Gemini access

What models does Chief use?

Chief uses whatever model is configured in your agent CLI. Each agent has its own model selection—see your agent's documentation for details.

Usage

Can I run Chief on a remote server?

Yes! Chief works great on remote servers. SSH in, run chief, press s to start the loop, and let it work. Use screen or tmux if you want to disconnect.

ssh my-server
tmux new -s chief
chief
# Press 's' to start the loop
# Ctrl+B D to detach

How do I resume after stopping?

Run chief again and press s to start. It reads state from prd.md and continues where it left off.

Can I edit the PRD while Chief is running?

Yes, but be careful. Chief re-reads prd.md between iterations. Edits to the current story might cause confusion.

Best practice: pause Chief with p (or stop with x), edit, then press s to resume.

Can I have multiple PRDs?

Yes. Create separate directories under .chief/prds/:

.chief/prds/
├── feature-a/
└── feature-b/

Run with chief feature-a or use the TUI: press n to open the PRD picker, or 1-9 to quickly switch between tabs. Multiple PRDs can run in parallel.

How do I skip a story?

Mark it as done manually in prd.md:

### US-003: Story Title

**Status:** done

Or remove it from the PRD entirely.

What are worktrees?

Git worktrees let you have multiple checkouts of a repository at the same time, each on a different branch. Chief uses worktrees to isolate parallel PRDs so they don't interfere with each other's files or commits. Each worktree lives at .chief/worktrees/<prd-name>/.

Do I have to use worktrees?

No. Chief asks on a PRD's first start, and "Create branch only" — the recommended answer everywhere except alongside a second run in the same directory — skips the worktree and works on chief/<name> in your current checkout. Worktrees are most useful when running multiple PRDs simultaneously.

The other direction is just as easy: whatever branch you press s from, "Create worktree + branch" is the option directly below the recommended one.

Why doesn't Chief ask me where to run when I restart a PRD?

Because the question is already answered. A PRD that has a branch or a worktree goes straight back to it: the worktree Chief created for it, the checkout you are in when it is already on the run's branch (which includes running chief from inside the PRD's own worktree), or the worktree holding chief/<name> from an earlier session. Answering again could only send the run somewhere that doesn't have the stories it already finished.

To run a PRD somewhere else, take its current home away first — clean the worktree from the picker, or check out a different branch when the run lives in your main checkout.

A worktree run changed files in my main checkout — why?

It shouldn't, and as of the current version it doesn't. A run given a worktree keeps the PRD's working files inside that worktree and writes its story statuses, progress.md, logs and summary there.

Earlier versions moved only the agent into the worktree and left chief's own bookkeeping in the project, so starting a PRD marked a story in-progress in the copy your branch had checked out — showing up as a modified prd.md and a new .chief/prds/<prd>/.gitignore on main or develop. Those changes could not even be committed: staging a path in the project from inside a worktree fails, so they accumulated as an uncommitted change and the merged branch came back without the progress the run had recorded.

If your checkout still carries those leftovers, they are safe to discard — the branch has the run's state, or the worktree cleanup will bring it home:

git checkout -- .chief/prds/<prd-name>/prd.md

How do I merge a completed branch?

Press n to open the PRD picker, select the completed PRD, and press m to merge. If there are conflicts, Chief shows the conflicting files and instructions for manual resolution.

How do I clean up a worktree?

Press n to open the PRD picker, select the PRD, and press c. You can choose to remove just the worktree or remove the worktree and delete the branch.

What happens if Chief crashes mid-worktree?

Chief detects orphaned worktrees on startup and marks them in the picker. You can clean them up with c. Your work on the branch is preserved — git worktrees are just directories with a separate checkout.

Can I automatically push and create PRs?

Yes. chief setup, which also runs on first launch, asks whether to push and open a pull request when a run finishes. You can also toggle these in the Settings TUI (,). Auto-PR requires the gh CLI to be installed and authenticated.

Technical

Why stream-json?

The agent outputs JSON in a streaming format. Chief uses stream-json to parse this in real-time, allowing it to:

• Display progress as it happens
• React to completion signals immediately
• Handle large outputs efficiently

Why conventional commits?

Conventional commits (feat:, fix:, etc.) provide:

• Clear history of what each story added
• Easy to review changes per-story
• Works with changelog generators

What if the agent makes a mistake?

Git is your safety net. Each story is committed separately, so you can:

# See what changed
git log --oneline

# Revert a story
git revert HEAD

# Or reset and re-run
git reset --hard HEAD~1
chief  # then press 's' to start

Does Chief work with any language?

Yes. Chief doesn't know or care what language you're using. It passes your PRD to the agent, which handles the implementation.

How does Chief handle tests?

Chief instructs the agent to run quality checks (tests, lint, typecheck) before committing. The agent infers the appropriate commands from your codebase (e.g., npm test, pytest).

Troubleshooting

See Common Issues

For specific problems and solutions.

Getting Help

Where can I report bugs?

GitHub Issues

Where do I ask questions?

Open a GitHub Issue — this is a small private fork, so there's no separate community forum.

Can I contribute?

Yes! See CONTRIBUTING.md in the repository.