Ralph runner
Run Ralph Wiggum autonomous coding loops. Use when user asks to run ralph, start autonomous coding, execute a PRD, implement features from a task list, or wants Claude Code to work through user stories iteratively.From its SKILL.md
npx -y skills add linuxlewis/agent-skills --skill ralph-runnerAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
2.6 KB, as published. Nobody here has run it
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