linuxlewis 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:
- Reads
prd.json, picks highest priority story wherepasses: false - Spawns fresh Claude Code instance
- Claude implements that ONE story
- Runs quality checks (typecheck, lint, tests)
- If passing: commits, updates
prd.json, appends toprogress.txt - 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
- Keep stories small - Each should complete in one context window
- Good acceptance criteria - Be specific about "done"
- Include typecheck - Add "Typecheck passes" to criteria
- Use context - Pass in AGENTS.md and relevant docs
- Check progress.txt - Contains learnings from previous iterations