Ralph
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. Memory persists via git history, progress.txt, and prd.json.
Based on Geoffrey Huntley's Ralph pattern.
Read my in-depth article on how I use Ralph
Prerequisites
- Claude Code installed and authenticated (
npm install -g @anthropic-ai/claude-code)
jq installed (brew install jq on macOS)- A git repository for your project
Setup
Option 1: Copy to your project
Copy the ralph files into your project:
# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh
Option 2: Install skills globally
Copy the skills to your Claude config for use across all projects:
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/
Option 3: Use as Claude Code Marketplace
Add the Ralph marketplace to Claude Code:
/plugin marketplace add snarktank/ralph
Then install the skills:
/plugin install ralph-skills@ralph-marketplace
Available skills after installation:
/prd - Generate Product Requirements Documents/ralph - Convert PRDs to prd.json format
Skills are automatically invoked when you ask Claude to:
- "create a prd", "write prd for", "plan this feature"
- "convert this prd", "turn into ralph format", "create prd.json"
Workflow
1. Create a PRD
Use the PRD skill to generate a detailed requirements document:
Load the prd skill and create a PRD for [your feature description]
Answer the clarifying questions. The skill saves output to tasks/prd-[feature-name].md.
2. Convert PRD to Ralph format
Use the Ralph skill to convert the markdown PRD to JSON:
Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
This creates prd.json with user stories structured for autonomous execution.
3. Run Ralph
./scripts/ralph/ralph.sh [max_iterations]
Default is 10 iterations.
Ralph will:
- Create a feature branch (from PRD
branchName)
- Pick the highest priority story where
passes: false
- Implement that single story
- Run quality checks (typecheck, tests)
- Commit if checks pass
- Update
prd.json to mark story as passes: true
- Append learnings to
progress.txt
- Repeat until all stories pass or max iterations reached
Key Files
| File | Purpose |
|---|
ralph.sh | The bash loop that spawns fresh Claude Code instances |
CLAUDE.md | Prompt template given to each Claude Code instance |
prd.json | User stories with passes status (the task list) |
prd.json.example | Example PRD format for reference |
progress.txt | Append-only learnings for future iterations |
skills/prd/ | Skill for generating PRDs |
skills/ralph/ | Skill for converting PRDs to JSON |
.claude-plugin/ | Plugin manifest for Claude Code marketplace discovery |
flowchart/ | Interactive visualization of how Ralph works |
Flowchart
View Interactive Flowchart - Click through to see each step with animations.
The flowchart/ directory contains the source code. To run locally:
cd flowchart
npm install
npm run dev
Critical Concepts
Each Iteration = Fresh Context
Each iteration spawns a new Claude Code instance with clean context. The only memory between iterations is:
- Git history (commits from previous iterations)
progress.txt (learnings and context)prd.json (which stories are done)
Small Tasks
Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.
Right-sized stories:
- Add a database column and migration
- Add a UI component to an existing page
- Update a server action with new logic
- Add a filter dropdown to a list
Too big (split these):
- "Build the entire dashboard"
- "Add authentication"
- "Refactor the API"
AGENTS.md Updates Are Critical
After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because AI coding tools automatically read these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.
Examples of what to add to AGENTS.md:
- Patterns discovered ("this codebase uses X for Y")
- Gotchas ("do not forget to update Z when changing W")
- Useful context ("the settings panel is in component X")
Feedback Loops