Ralph Wiggum
An autonomous AI agent loop for Claude Code that runs until all PRD items are complete.
Each iteration is a fresh instance with clean context. Memory persists via git history.
Based on Geoffrey Huntley's Ralph pattern.
Fork: This project is a fork of snarktank/ralph.
Security Warning
Ralph runs AI agents autonomously with full access to your codebase. Before running:
- Never expose production credentials - Ralph could accidentally commit, log, or transmit sensitive values like
AWS_ACCESS_KEY_ID, DATABASE_URL, or API keys
- Use sandboxing - Run Ralph in a Docker container, VM, or isolated sandbox environment to limit potential damage
- Review commits before pushing - Always review what Ralph committed before pushing to remote
See docs/SECURITY.md for complete security guidance, including pre-flight checklists and emergency stop procedures.
Why This Exists
AI coding assistants lose context on large tasks. By the time they reach the end, they have forgotten the beginning.
Ralph solves this by:
- Starting fresh each iteration - Every task begins with full context capacity
- Persisting memory in git - Commits,
progress.txt, and prd.json carry knowledge forward
- Keeping tasks small - Each story fits comfortably in one context window
The result: autonomous task completion that does not degrade over time.
Who This Is For
- Solo developers who want to ship while they sleep
- Small teams who want to multiply their output
- Anyone who has a clear PRD and wants autonomous execution
Ralph works best when you have:
- Well-defined, testable acceptance criteria
- A codebase with type checking and tests
- Tasks that can be broken into small, independent stories
How It Works
┌─────────────────────────────────────────────────────────────┐
│ ralph.sh loop │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Spawn fresh Claude Code instance │
│ ↓ │
│ 2. Read prd.json → pick next story (passes: false) │
│ ↓ │
│ 3. Read progress.txt → learn from previous iterations │
│ ↓ │
│ 4. Implement the story │
│ ↓ │
│ 5. Run quality checks (typecheck, lint, test) │
│ ↓ │
│ 6. If passing: commit, mark story passes: true │
│ ↓ │
│ 7. Append learnings to progress.txt │
│ ↓ │
│ 8. All stories done? → EXIT │
│ More stories? → LOOP (back to step 1) │
│ │
└─────────────────────────────────────────────────────────────┘
Getting Started
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
Installation
Step 1: Copy Ralph to your project (required)
# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph-wiggum/ralph.sh scripts/ralph/
cp /path/to/ralph-wiggum/CLAUDE.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh
Step 2: Install skills (choose one)
Option A: Install skills globally
cp -r /path/to/ralph-wiggum/skills/prd ~/.claude/skills/
cp -r /path/to/ralph-wiggum/skills/ralph ~/.claude/skills/
Option B: Install skills locally to project
# From your project root
mkdir -p .claude/skills
cp -r /path/to/ralph-wiggum/skills/prd .claude/skills/
cp -r /path/to/ralph-wiggum/skills/ralph .claude/skills/
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: