ralph-cli

Automated Claude Code workflow runner. Define tasks in a PRD, then let Claude work through them hands-free — one task per iteration, with git commits along the way.

Install

git clone <repo-url> && cd ralph-cli
pnpm install && pnpm build
pnpm link --global

Quick Start

cd your-project
ralph init --name "My Project"
# Edit prd.json with your requirements
ralph run

Commands

ralph init [--name "Project"]

Scaffolds three files in the current directory (skips existing):

• prd.json — PRD template with example task
• progress.txt — empty progress log
• CLAUDE.md — instructions for Claude

ralph run [iterations]

Runs an automated loop (default: 10 iterations). Each iteration Claude:

1. Picks the highest-priority incomplete task
2. Implements it
3. Updates progress.txt and sets passes: true in the PRD
4. Makes a git commit

Stops early if Claude outputs <promise>COMPLETE</promise> (all tasks done).

ralph run        # 10 iterations
ralph run 5      # 5 iterations

ralph once

Runs Claude interactively for a single task with stdio: inherit. You can watch and intervene. Uses acceptEdits permission mode by default.

ralph status

Shows PRD completion progress — no Claude invocation.

=== My Project — PRD Status ===

  ✔ TASK-001         high    Set up project structure
  ○ TASK-002         medium  Add authentication

  1/2 complete (50%)

Flags

Available on run and once:

Flag	Description	Default
--sandbox	Run via docker sandbox run claude	off
--model <model>	Claude model (e.g. opus, sonnet)	—
--prd <path>	PRD file path	prd.json
--progress <path>	Progress file path	progress.txt
--permission-mode <mode>	Permission mode	bypassPermissions (run) / acceptEdits (once)
--max-budget <usd>	Max budget per iteration	—

Project Config

Create ralph.config.json in your project root to set defaults (CLI flags override):

{
  "model": "sonnet",
  "sandbox": true,
  "maxBudget": 3
}

PRD Format

The PRD is a JSON file with this structure:

{
  "projectName": "My Project",
  "requirements": [
    {
      "id": "TASK-001",
      "category": "Feature",
      "priority": "high",
      "description": "Short description",
      "details": "Detailed implementation notes...",
      "stepsToVerify": ["Step 1", "Step 2"],
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
      "passes": false
    }
  ]
}

Set passes: true when a task is complete. Claude does this automatically during run/once.

Requirements

• Node.js >= 18
• Claude Code CLI installed
• Docker (only if using --sandbox)