!Chief CLI

Chief CLI

CLI tool that codifies the Ralph Wiggum technique.

Installation

``bash
npm install -g chief-cli
`

Or use with npx:

`bash
npx chief-cli init
`

Requirements

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

Quick Start

`bash


Initialize a new project

chief init

Create specifications

chief spec

Generate implementation plan

chief plan

Implement from the plan

chief build

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

chief afk
`

Commands

$3

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

`bash
chief init
chief init --force # Overwrite existing files
`

Options:

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

Creates:

- ralph.config.json - Project configuration
- ralph_files/prompts/claude/PROMPT_plan.md - Claude planning prompt
- ralph_files/prompts/claude/PROMPT_build.md - Claude building prompt
- ralph_files/prompts/claude/PROMPT_spec.md - Claude spec generation prompt
- ralph_files/prompts/codex/PROMPT_plan.md - Codex planning prompt
- ralph_files/prompts/codex/PROMPT_build.md - Codex building prompt
- ralph_files/prompts/codex/PROMPT_spec.md - Codex spec generation prompt
- ralph_files/WHAT_TO_BUILD.md - Example specification

$3

Interactive wizard to create specification files.

`bash
chief spec
chief spec --model claude-opus # Use Claude Opus for spec generation
`

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:

- -m, --model - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)

$3

Run planning mode - analyzes specs and creates/updates the implementation plan.
After planning, you can optionally launch build mode and choose its max iterations.

`bash
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 - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
- -u, --unlimited - Run unlimited iterations

$3

Run building mode - implements tasks from the plan.

`bash
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 - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)
- -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.

$3

Run spec → plan → build in a single interactive flow.

`bash
chief afk
`

Options:

- -m, --model - AI model to use (claude-haiku, claude-sonnet, claude-opus, codex-5.1-mini, codex-5.2, codex-5.1-max)

$3

Move an existing ralph_files/specs/JTBD.md file to ralph_files/WHAT_TO_BUILD.md.

`bash
chief update
`

Use this to migrate older projects to the new WHAT_TO_BUILD naming.

$3

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

`bash
chief clean
`

This command:

- Archives current WHAT_TO_BUILD.md content to ralph_files/archive/
- Uses AI to detect completed specs based on the implementation plan
- Archives completed specs to ralph_files/archive/specs/
- Moves remaining TODO items into ralph_files/WHAT_TO_BUILD.md
- Archives the implementation plan to ralph_files/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.

$3

Display help information for all Chief commands.

`bash
chief help
`

Shows usage, available commands, and common options.

Available Models

Chief supports multiple AI models with direct model selection:

| Agent | Model | Description |
| ------ | ------------------ | --------------------------------------------------------- |
| claude | haiku | Fast, cost-effective model for quick tasks |
| claude | sonnet | Balanced model for standard development work |
| claude | opus | Most capable model for complex reasoning and architecture |
| codex | gpt-5.1-codex-mini | Fast, cost-effective Codex model |
| codex | gpt-5.2-codex | Balanced Codex model |
| codex | gpt-5.1-codex-max | Most capable Codex model |

Configuration

Edit ralph.config.json to customize:

`json
{
"agent": "claude",
"model": "sonnet",
"specMode": { "agent": "claude", "model": "opus" },
"planMode": { "agent": "claude", "model": "opus", "maxIterations": 5 },
"buildMode": { "agent": "claude", "model": "sonnet", "maxIterations": 5 },
"agentFlags": {
"dangerouslySkipPermissions": true,
"outputFormat": "stream-json",
"verbose": true
},
"paths": {
"specs": "ralph_files/specs",
"ralphFiles": "ralph_files",
"src": "src",
"prompts": "ralph_files/prompts",
"plan": "ralph_files/IMPLEMENTATION_PLAN.md"
},
"git": {
"remoteName": "origin"
},
"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
- 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)
- agentFlags - Flags passed to the AI agent CLI
- paths - Customize file and directory locations
- paths.ralphFiles - Root directory for Ralph files
- git.remoteName - Git remote name
- variables - Custom variables for template rendering

The Ralph Wiggum Technique

Ralph is an autonomous AI coding workflow and term coined by Geoff Huntley:

1. Write Specifications - Define what you want to build in ralph_files/specs/
2. Plan - AI analyzes specs and creates an implementation plan
3. Build - AI implements tasks from the plan, committing as it goes
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
- Subagents enable massive parallelism for research and implementation
- Git commits preserve progress

Writing Good Specifications

Specifications should include:

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

- 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 ralph_files/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:

`markdown


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-.md to prevent reprocessing.

Pre-commit Hooks

We 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.

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

`bash


Install prek

npm install -g prek

In your project directory, enable hooks

prek install

Add hooks to .pre-commit-config.yaml

`

Example configuration:

`yaml
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.

Local Development

To work on Chief CLI locally and test your changes:

`bash


In the chief-cli directory, create a global symlink

npm link

Now 'chief' command uses your local version

chief --version

To unlink when done

npm unlink -g chief-cli
`

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

`bash


In the chief-cli directory

npm link

In your other project directory

npm link chief-cli

To unlink

npm unlink chief-cli
``

License

MIT