ralph-cli

CLI for running Ralph Wiggum loops with Claude Code.

Ralph is an autonomous AI agent loop that runs Claude Code repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context.

Installation

# Clone and install locally
git clone https://github.com/linuxlewis/ralph-cli.git
cd ralph-cli
npm install
npm run build
npm link

This installs ralph globally on your PATH.

Requires:

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

Quick Start

# Run Ralph on a PRD file
ralph run prd.json

# With context files
ralph run prd.json --context AGENTS.md --context docs/

# Check progress
ralph status prd.json

Commands

ralph run <prd>

Run the Ralph loop on a PRD file.

ralph run prd.json [options]

Options:

• -i, --iterations <n> - Maximum iterations (default: 10)
• -c, --context <paths...> - Context files or directories to include
• -p, --prompt <path> - Custom prompt template (default: built-in)
• --headed - Run Claude Code with visible output
• --dry-run - Show prompt without executing

Examples:

# Basic usage
ralph run tasks/auth.prd.json

# More iterations, with context
ralph run prd.json --iterations 20 --context ./docs --context AGENTS.md

# See what would be sent to Claude
ralph run prd.json --dry-run

ralph status [prd]

Show progress status for a PRD.

ralph status prd.json

Shows:

• Overall progress (X/Y stories complete)
• Each story with pass/fail status
• Sorted by priority

PRD Format

{
  "project": "MyApp",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add user login",
      "description": "As a user, I want to log in...",
      "acceptanceCriteria": [
        "Login form with email/password",
        "Validation errors shown",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

How It Works

1. Ralph reads prd.json and picks the highest priority story where passes: false
2. Claude Code implements that single story
3. Quality checks run (typecheck, lint, tests)
4. If passing, commits and updates prd.json to mark story complete
5. Appends learnings to progress.txt
6. Loop repeats until all stories pass or max iterations reached

Each iteration spawns a fresh Claude Code instance. Memory persists via:

• Git history (commits from previous iterations)
• progress.txt (learnings and context)
• prd.json (which stories are done)

Custom Prompts

The built-in prompt works for most projects. To customize:

ralph run prd.json --prompt my-prompt.md

See the default prompt for the expected format.

Context Files

Add context to help Claude understand your codebase:

# Single files
ralph run prd.json -c AGENTS.md -c docs/api.md

# Entire directory (loads all .md files)
ralph run prd.json -c ./docs

# Multiple sources
ralph run prd.json -c AGENTS.md -c ./docs -c ./architecture

Context is appended to the prompt as ## Context: filename sections.

License

MIT