Chief CLI

A CLI tool to make running agents in a loop easier and more effective.

What does it do?

Chief provides several helper commands that simplify the process of taking an idea for what you want to build and turning that into a series of specs, a plan, and then works that plan while optimizing the context window of the agent.

How do I get started?

1. After installing Chief in the root of your project, run the chief init command to generate the Chief config and .chief folder.
2. Switch to a git branch that you want to work on.
3. Open up the .chief/WHAT_TO_BUILD.md file and put in a few sentences that quickly describe something you want to do. In the future, feel free to put links to Linear tickets (or other MCP supported data sources) or even copy and paste the full contents of a PRD into the doc.
4. Run chief afk (away from keyboard) and accept the defaults.

What do I do next?

The chief afk command is the most efficient way to use Chief, however, after you have gone through the getting started steps, we recommend exploring running the Chief commands in sequence manually, though this can be a little bit more tedious, it allows you the opportunity to step in and adjust specifications and the plan before we begin building against the plan. This can be extremely valuable in terms of allowing Chief to be the most effective.

You should also read the prompts that are used within Chief. Take a look at .chief/prompts/claude/PROMPT_build.md for example to see the "magic" that allows Chief to do what it does. You should feel free to edit this file for your repo to make it more effective, but keep in mind that you should already have an AGENTS.md and/or other agent-related files that are also going to be pulled into a session. Try not to be too prescriptive in this prompt. Less is more.

Installation

npm install -g chief-cli

Or use with npx:

npx chief-cli init

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated

Quick Start

# Initialize a new project
chief init

# Create specifications
chief spec

# Generate implementation plan
chief plan

# Implement from the plan
chief build

# Review implementation quality
chief review

# Create a pull request with auto-generated description
chief pr

# Run spec → plan → build → review → clean in one flow (we recommend not using this until you get better at the inputs that drive specs)
chief afk

Commands

Global Options

These options apply to all commands:

• -y, --non-interactive - Auto-select defaults for all prompts (also: CHIEF_NON_INTERACTIVE=true)
• -v, --version - Output the current version

chief init

Initialize a new Chief project. Creates all necessary configuration and prompt files.

chief init
chief init --force         # Overwrite existing files

Options:

• -f, --force - Overwrite existing files without prompting

Creates:

• chief.config.json - Project configuration
• .chief/prompts/claude/PROMPT_plan.md - Claude planning prompt
• .chief/prompts/claude/PROMPT_build.md - Claude building prompt
• .chief/prompts/claude/PROMPT_spec.md - Claude spec generation prompt
• .chief/prompts/claude/PROMPT_review.md - Claude review prompt
• .chief/prompts/claude/PROMPT_pr.md - Claude PR creation prompt
• .chief/prompts/codex/PROMPT_plan.md - Codex planning prompt
• .chief/prompts/codex/PROMPT_build.md - Codex building prompt
• .chief/prompts/codex/PROMPT_spec.md - Codex spec generation prompt
• .chief/prompts/codex/PROMPT_review.md - Codex review prompt
• .chief/prompts/codex/PROMPT_pr.md - Codex PR creation prompt
• .chief/WHAT_TO_BUILD.md - Example specification

chief afk

Run spec → plan → build → review → clean in a single autonomous workflow. You can run in interactive mode (prompted for iterations) or non-interactive mode (specify iterations as positional arguments).

# Interactive mode - prompts for plan and build iterations
chief afk

# Non-interactive mode - specify iterations directly
chief afk 5 10              # 5 plan iterations, 10 build iterations
chief afk 0 0               # Unlimited plan and build iterations
chief afk 3 0               # 3 plan iterations, unlimited build

Positional Arguments:

• [planIterations] - Number of plan iterations to run (0 for unlimited). If omitted, you'll be prompted.
• [buildIterations] - Number of build iterations to run (0 for unlimited). If omitted, you'll be prompted.

Options:

• -m, --model <model> - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
• -a, --agent <agent> - AI agent to use (claude or codex)
• -w, --what <input...> - Input to write to WHAT_TO_BUILD.md (text or URLs)
• --plan-loops <n> - Number of plan iterations (0 for unlimited); takes precedence over positional arg
• --build-loops <n> - Number of build iterations (0 for unlimited); takes precedence over positional arg

Graceful Termination:

Press Ctrl-C (SIGINT) to gracefully terminate the AFK workflow. The workflow will finish its current phase (spec, plan, build, review, or clean) and exit cleanly at the next phase boundary rather than terminating mid-execution. The process will exit with code 130.

This is different from the q key behavior in build mode, which stops after the current iteration within the build phase.

chief spec

Interactive wizard to create specification files.

chief spec
chief spec --model claude-opus  # Use Claude Opus for spec generation
chief spec -w "Build OAuth login and account linking"  # Inline WHAT_TO_BUILD input
chief spec "Build OAuth login and account linking"     # Positional input (also supported)

Automatically creates specs from your WHAT_TO_BUILD.md file

-or-

Guides you through:

• Naming the spec
• Defining the Job to Be Done (JTBD)
• Setting Acceptance Criteria

Options:

• -w, --what <input...> - Input to write to WHAT_TO_BUILD.md (text or URLs)
• -m, --model <model> - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
• -a, --agent <agent> - AI agent to use (claude or codex)
• --clarify - Ask clarifying questions before generating specs
• --no-clarify - Skip clarifying questions, generate specs directly

chief plan

Run planning mode - analyzes specs and creates/updates the implementation plan. The planning phase estimates the number of build loop iterations needed for implementation and includes guidance on stacked PR branching strategies for breaking work into smaller, reviewable pull requests.

After planning, you can optionally launch build mode and choose its max iterations.

chief plan
chief plan 3                    # Run 3 iterations
chief plan --model claude-haiku # Use Claude Haiku model
chief plan --unlimited          # Run unlimited iterations

Options:

• [iterations] - Number of iterations to run (positional argument)
• -m, --model <model> - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
• -a, --agent <agent> - AI agent to use (claude or codex)
• -u, --unlimited - Run unlimited iterations

chief build

Run building mode - implements tasks from the plan.

chief build
chief build 10                  # Run 10 iterations
chief build --model claude-opus # Use Claude Opus model
chief build --skip-plan-check   # Skip checking for implementation plan
chief build --unlimited         # Run unlimited iterations

Options:

• [iterations] - Number of iterations to run (positional argument)
• -m, --model <model> - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
• -a, --agent <agent> - AI agent to use (claude or codex)
• -u, --unlimited - Run unlimited iterations
• --skip-plan-check - Skip checking for implementation plan

While a run is in progress, you can press q to stop after the current iteration. This is a great way to interrupt a run while still letting the agent finish its current train of thought, rather than cutting it off mid-step.

chief review

Analyze implementation quality and code changes. Reviews the current state of your code against the implementation plan and specifications.

chief review
chief review 3                  # Run 3 iterations
chief review --model claude-opus # Use Claude Opus model
chief review --unlimited        # Run unlimited iterations

After a successful review, you'll be prompted to create a pull request.

Options:

• [iterations] - Number of iterations to run (positional argument)
• -m, --model <model> - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
• -a, --agent <agent> - AI agent to use (claude or codex)
• -u, --unlimited - Run unlimited iterations

Note: The review command will warn but continue if the implementation plan or specs directory is missing.

chief pr

Create a pull request with an auto-generated title and description based on your code changes.

chief pr always creates draft pull requests by default. This is intentional — it gives you a chance to review the auto-generated description and make edits before marking the PR ready for review. You can change the default by setting prMode.draft: false in chief.config.json.

chief pr
chief pr --model claude-opus    # Use Claude Opus for PR description

Options:

• -m, --model <model> - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
• -a, --agent <agent> - AI agent to use (claude or codex)

Requirements:

• GitHub CLI (gh) must be installed and authenticated
• Must be on a git branch (not detached HEAD)

The PR description is generated by analyzing your git diff, implementation plan, and specifications.

chief clean

Reset your Chief project to a clean state by archiving completed work.

chief clean

This command:

• Archives current WHAT_TO_BUILD.md content to .chief/archive/
• Uses AI to detect completed specs based on the implementation plan
• Archives completed specs to .chief/archive/specs/
• Moves remaining TODO items into .chief/WHAT_TO_BUILD.md
• Archives the implementation plan to .chief/archive/
• Resets WHAT_TO_BUILD.md to template state

Use this when you've completed a development cycle and want to start fresh with new requirements.

chief update

Migrate and update your Chief CLI project to the latest version. This command:

• Migrates legacy prompt files to agent-specific directories (prompts/claude/, prompts/codex/)
• Creates missing prompt files (PROMPT_spec.md, PROMPT_plan.md, PROMPT_build.md, PROMPT_review.md, PROMPT_pr.md)
• Leaves existing prompt files unchanged
• Migrates legacy configuration format to the new agent/model format

chief update

You'll be prompted to select which AI agents (Claude, Codex) to update prompt files for. Use this command when upgrading to a new version of Chief CLI or when prompt templates have been updated.

chief info

Display configuration information about your Chief CLI setup.

chief info
chief info --json              # Output in JSON format

Shows:

• Configuration source and settings
• Agent and model configuration for each mode
• File system paths
• MCP (Model Context Protocol) server status (when using Claude)

Options:

• --json - Output information in JSON format

chief help

Display help information for all Chief commands.

chief help

Shows usage, available commands, and common options.

Available Models

Chief supports multiple AI models with direct model selection:

Configuration

Edit chief.config.json to customize:

{
  "agent": "claude",
  "model": "sonnet",
  "specMode": { "agent": "claude", "model": "opus", "clarifyMode": "off" },
  "planMode": { "agent": "claude", "model": "opus", "maxIterations": 5 },
  "buildMode": { "agent": "claude", "model": "sonnet", "maxIterations": 5 },
  "reviewMode": { "agent": "claude", "model": "sonnet", "maxIterations": 1 },
  "prMode": {
    "agent": "claude",
    "model": "sonnet",
    "maxIterations": 1,
    "draft": true
  },
  "agentFlags": {
    "dangerouslySkipPermissions": true,
    "outputFormat": "stream-json",
    "verbose": true
  },
  "paths": {
    "specs": ".chief/specs",
    "projectDir": ".chief",
    "src": "src",
    "prompts": ".chief/prompts",
    "plan": ".chief/IMPLEMENTATION_PLAN.md"
  },
  "git": {
    "remoteName": "origin"
  },
  "beads": {
    "enabled": false,
    "issuePrefix": "PROJ"
  },
  "variables": {}
}

Configuration options:

• agent - Default agent: "claude" or "codex"
• model - Default model name passed to the agent (see table above)
• specMode.agent - Override agent for spec generation
• specMode.model - Override model for spec generation
• specMode.clarifyMode - Control clarifying questions: "off", "on", or "auto" (default: "off"); automatically skipped in AFK and non-interactive flows
• planMode.agent - Override agent for planning mode
• planMode.model - Override model for planning mode
• planMode.maxIterations - Max planning iterations (default: 5)
• buildMode.agent - Override agent for build mode
• buildMode.model - Override model for build mode
• buildMode.maxIterations - Max build iterations (0 = unlimited)
• reviewMode.agent - Override agent for review mode
• reviewMode.model - Override model for review mode
• reviewMode.maxIterations - Max review iterations (default: 1)
• prMode.agent - Override agent for PR creation mode
• prMode.model - Override model for PR creation mode
• prMode.maxIterations - Max PR iterations (default: 1)
• prMode.draft - Create PRs as drafts by default (default: true)
• agentFlags - Flags passed to the AI agent CLI
• paths - Customize file and directory locations
• paths.projectDir - Root directory for Chief files
• git.remoteName - Git remote name
• beads.enabled - Enable Beads issue tracking integration (default: false)
• beads.issuePrefix - Prefix for issue identifiers (e.g. "PROJ")
• variables - Custom variables for template rendering

Looping

1. Write Specifications - Define what you want to build in .chief/specs/
2. Plan - AI analyzes specs and creates an implementation plan. Multiple loops.
3. Build - AI implements tasks from the plan, committing as it goes. Multiple loops.
4. Iterate - The plan evolves as implementation progresses

Key principles:

• Specs drive everything - the AI reads them to understand requirements
• The Implementation Plan is the source of truth for what needs doing (IMPLEMENTATION_PLAN.md)
• Subagents enable massive parallelism for research and implementation
• Git commits preserve progress

Writing Good Specifications

Specifications ideally include:

1. Job to Be Done (JTBD) - What problem does this solve?

   • Recommended, but not required format: "When [situation], I want to [motivation], so that [outcome]"

2. Topics of Concern - What aspects need consideration?

   • Security, performance, edge cases, integrations, etc.

3. Acceptance Criteria - How do we know it's done?

   • Testable conditions that must be true

Using WHAT_TO_BUILD.md for Bulk Spec Generation

The key to success with Chief is providing clear, well-defined Jobs to Be Done.

Create .chief/WHAT_TO_BUILD.md and run chief spec to auto-generate specs from your JTBDs.

Tips:

• Be specific about the user's situation, motivation, and desired outcome
• You can paste an entire PRD (Product Requirements Document) into WHAT_TO_BUILD.md
• Use H2 headers (##) to separate distinct features or jobs
• Include Linear URLs for automatic ticket integration

Example WHAT_TO_BUILD.md:

## User Authentication

When a new user visits the app, I want to create an account securely,
so that I can access personalized features.

Linear: https://linear.app/team/issue/PROJ-123

## Dashboard Analytics

When I'm managing my business, I want to see key metrics at a glance,
so that I can make informed decisions quickly.

After processing, the file is renamed to WHAT_TO_BUILD.processed-<timestamp>.md to prevent reprocessing.

Beads Mode

Chief supports an alternative workflow powered by Beads, a local-first issue tracking system that stores tasks in a SQLite database (.beads/beads.db). Enable it by setting beads.enabled: true in your config. The bd CLI must be installed when beads mode is enabled.

The two modes (markdown and beads) are fully independent and can be switched without conflict. When beads mode is disabled (the default), Chief behaves exactly as described in the rest of this README.

In beads mode, the workflow maps to beads concepts:

• Spec phase creates epics. Each spec becomes an epic bead preserving the JTBD, acceptance criteria, and topics. Inter-spec dependencies become inter-epic dependencies.
• Plan phase decomposes epics into task beads with dependency relationships. The LLM outputs structured JSON that gets converted into beads with hard/soft dependency wiring.
• Build phase skips the plan-file check and uses bd prime to inject current task context into the agent prompt.
• Clean phase closes completed epics and syncs the beads database.

Pre-commit Hooks

We highly recommend using pre-commit hooks to catch issues before they're committed. This is especially valuable when working with AI-generated code, as it ensures code quality and consistency. Backpressure helps the Agent immensely.

We recommend prek as a fast, cross-platform pre-commit hook manager:

# Install prek
npm install -g prek

# In your project directory, enable hooks
prek install

# Add hooks to .pre-commit-config.yaml

Example prek configuration:

repos:
  - repo: local
    hooks:
      - id: typecheck
        name: TypeScript type check
        entry: npx tsc --noEmit
        language: system
        pass_filenames: false

      - id: tests
        name: Run tests
        entry: npm test
        language: system
        pass_filenames: false

Pre-commit hooks help maintain code quality by running checks automatically before each commit, catching issues early in the development process.

AI_AGENT Environment Variable

When Chief runs an agent loop, it sets AI_AGENT=<agent-name> for the duration of the agent session (e.g. AI_AGENT=claude-code or AI_AGENT=openai-codex). This follows the Vercel standard for identifying the active coding agent.

Humans often dislike heavy pre-commit hooks because they interrupt flow. Agents love them. They create backpressure and steer the next iteration. Keep hooks fast and actionable (linting, type checking, and running targeted/dirty unit tests):

#!/bin/sh
if [ -n "$AI_AGENT" ]; then
  echo "Coding agent commit ($AI_AGENT): running fast feedback checks."
  npm run lint || exit 1
  npx tsc --noEmit || exit 1
  npm run test:dirty || exit 1
  exit 0
fi

This keeps the agent moving quickly with strong feedback signals, without paying the cost of full integration or end-to-end suites on every agent commit.

CHIEF_DEBUG Environment Variable

Set CHIEF_DEBUG=true to enable verbose debug logging from Chief itself. This prints internal state and tool call details, useful when diagnosing unexpected behavior.

CHIEF_DEBUG=true chief build

Local Development

To work on Chief CLI locally and test your changes:

# Build the project first
npm run build

# Create a global symlink
npm link

# Now 'chief' command uses your local version
chief --version

# When actively developing, use watch mode to rebuild on changes
npm run dev

# To unlink when done
npm unlink -g chief-cli

If you're developing another project that depends on chief-cli:

# In the chief-cli directory
npm run build && npm link

# In your other project directory
npm link chief-cli

# To unlink
npm unlink chief-cli

License

MIT