Chief CLI

CLI tool that codifies the Ralph methodology for autonomous AI coding with Claude Code or OpenAI Codex.

Installation

npm install -g chief-cli

Or use with npx:

npx chief-cli init

Requirements

• Node.js 18+
• Claude Code CLI or OpenAI Codex 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

Commands

chief init

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

chief init
chief init --force         # Overwrite existing files
chief init --agent codex   # Initialize for OpenAI Codex

Options:

• -f, --force - Overwrite existing files without prompting
• -a, --agent <agent> - AI agent to use (claude, codex)

• ralph.config.json - Project configuration
• ralph_files/PROMPT_plan.md - Planning mode prompt
• ralph_files/PROMPT_build.md - Building mode prompt
• AGENTS.md - Operational guide
• ralph_files/specs/JTBD.md - Example specification
• ralph_files/RALPH_README.md - Project documentation

chief spec

Interactive wizard to create specification files.

chief spec

Guides you through:

• Naming the spec
• Defining the Job to Be Done (JTBD)
• Adding Topics of Concern
• Setting Acceptance Criteria

chief plan

Run planning mode - analyzes specs and creates/updates the implementation plan.

chief plan
chief plan 3                    # Run 3 iterations
chief plan --model-tier fast    # Use fast tier
chief plan --unlimited          # Run unlimited iterations
chief plan --agent codex        # Use Codex instead of Claude

Options:

• [iterations] - Number of iterations to run (positional argument)
• -a, --agent <agent> - AI agent to use (claude, codex)
• -t, --model-tier <tier> - Model tier to use (fast, standard, reasoning)
• -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-tier reasoning
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)
• -a, --agent <agent> - AI agent to use (claude, codex)
• -t, --model-tier <tier> - Model tier to use (fast, standard, reasoning)
• -u, --unlimited - Run unlimited iterations
• --skip-plan-check - Skip checking for implementation plan

Model Tiers

Chief uses agent-agnostic model tiers that map to the best model for each capability level:

Configuration

Edit ralph.config.json to customize:

{
  "agent": "claude",
  "modelTier": "standard",
  "specMode": { "modelTier": "reasoning" },
  "planMode": { "modelTier": "reasoning", "maxIterations": 5 },
  "buildMode": { "modelTier": "standard", "maxIterations": 0 },
  "agentFlags": {
    "dangerouslySkipPermissions": true,
    "outputFormat": "stream-json",
    "verbose": true
  },
  "paths": {
    "specs": "ralph_files/specs",
    "src": "src",
    "prompts": "ralph_files",
    "plan": "ralph_files/IMPLEMENTATION_PLAN.md",
    "agents": "AGENTS.md"
  },
  "git": {
    "autoPush": true,
    "remoteName": "origin"
  },
  "variables": {}
}

Configuration options:

• agent - AI agent to use: "claude" or "codex"
• modelTier - Default model tier: "fast", "standard", or "reasoning"
• specMode.modelTier - Override tier for spec generation
• planMode.modelTier - Override tier for planning mode
• planMode.maxIterations - Max planning iterations (default: 5)
• buildMode.modelTier - Override tier for build mode
• buildMode.maxIterations - Max build iterations (0 = unlimited)
• agentFlags - Flags passed to the AI agent CLI
• paths - Customize file and directory locations
• git.autoPush - Automatically push commits to remote
• git.remoteName - Remote name for auto-push
• variables - Custom variables for template rendering

The Ralph Methodology

Ralph is an autonomous AI coding workflow:

• Write Specifications - Define what you want to build in ralph_files/specs/
• Plan - AI analyzes specs and creates an implementation plan
• Build - AI implements tasks from the plan, committing as it goes
• Iterate - The plan evolves as implementation progresses

• 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; auto-push keeps the remote updated

Writing Good Specifications

Specifications should include:

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

• Format: "When [situation], I want to [motivation], so that [outcome]"

• Topics of Concern - What aspects need consideration?

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

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

• Testable conditions that must be true

Local Development

To work on Chief CLI locally and test your changes:

# 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:

# In the chief-cli directory
npm link

# In your other project directory
npm link chief-cli

# To unlink
npm unlink chief-cli

License

MIT