linuxlewis/ralph-runner

Ralph Runner

Run autonomous AI coding loops that implement features from a PRD (Product Requirements Document) iteratively.

Prerequisites

• Claude Code - claude --version
• ralph-cli - ralph --version

Quick Start

# Check status of a PRD
ralph status prd.json

# Run the loop
ralph run prd.json

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

# More iterations
ralph run prd.json --iterations 20

Workflow

1. Create PRD

Create a prd.json file with user stories:

{
  "project": "MyApp",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login form",
      "priority": 1,
      "passes": false
    }
  ]
}

2. Run Ralph

ralph run prd.json --context AGENTS.md

3. Monitor Progress

ralph status prd.json

How It Works

Each iteration:

1. Reads prd.json, picks highest priority story where passes: false
2. Spawns fresh Claude Code instance
3. Claude implements that ONE story
4. Runs quality checks (typecheck, lint, tests)
5. If passing: commits, updates prd.json, appends to progress.txt
6. Outputs <promise>COMPLETE</promise> when all done

Memory persists via:

• Git history (commits)
• progress.txt (learnings)
• prd.json (status)

CLI Reference

ralph run <prd>

ralph run prd.json [options]

Options:
  -i, --iterations <n>    Max iterations (default: 10)
  -c, --context <paths>   Context files/dirs to include
  -p, --prompt <path>     Custom prompt template
  --headed                Show Claude output live
  --dry-run               Preview without running

ralph status [prd]

ralph status prd.json

Shows progress bar and story status.

PRD Format

See references/prd-format.md for complete format specification.

Best Practices

1. Keep stories small - Each should complete in one context window
2. Good acceptance criteria - Be specific about "done"
3. Include typecheck - Add "Typecheck passes" to criteria
4. Use context - Pass in AGENTS.md and relevant docs
5. Check progress.txt - Contains learnings from previous iterations