CLI that makes the Ralph Wiggum technique easy
npm install chief-cliCLI tool that codifies the Ralph Wiggum technique.
``bash`
npm install -g chief-cli
Or use with npx:
`bash`
npx chief-cli init
- Node.js 18+
- Claude Code CLI installed and authenticated
`bashInitialize a new project
chief init
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 promptingCreates:
-
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 planWhile 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 stateUse 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 renderingThe 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 progressesKey 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 integrationExample 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- 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 prekIn your project directory, enable hooks
prek installAdd 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 linkNow 'chief' command uses your local version
chief --versionTo 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 linkIn your other project directory
npm link chief-cliTo unlink
npm unlink chief-cli
``MIT