The Ralph Wiggum Loop: Running AI Agents for Hours, Not Minutes
TL;DR
The Ralph Wiggum Loop is a technique where you feed Claude Code the same prompt repeatedly. Each iteration, Claude sees its previous work in files and git history, self-corrects, and makes incremental progress. The result: Complex tasks run autonomously for hours or days - while you sleep.
The Problem: Context is Finite
Anyone working with AI coding assistants knows the feeling: You’re in the middle of a complex refactor, Claude finally understands the context, and then - Context window exhausted. Restart. Explain everything again.
Geoffrey Huntley faced exactly this problem. His solution? A bash loop so simple it’s almost audacious:
while :; do
cat PROMPT.md | claude-code --continue
done
The name? A tribute to Ralph Wiggum from The Simpsons - someone who just keeps going despite all odds.
How It Works
The magic lies in iteration with memory:
- Prompt is stored - Your task lands in a state file
- Claude works - Reads files, makes changes, commits
- Claude tries to stop - Thinks it’s done
- Hook intercepts - Checks for a “promise tag” like
<promise>DONE</promise> - Not found? - Prompt gets re-injected, next iteration starts
Each iteration, Claude sees:
- The modified files from previous runs
- The git history with commit messages
- The todo list with remaining tasks
Claude corrects its own mistakes, continues where it left off, and converges step by step toward the solution.
Installation in 30 Seconds
Ralph Wiggum is an official Anthropic plugin:
/plugin install ralph-wiggum@claude-plugins-official
Start a loop:
/ralph-loop "Migrate all tests from Jest to Vitest.
Output <promise>MIGRATION COMPLETE</promise> when done." \
--max-iterations 30
Cancel anytime with:
/cancel-ralph
When Ralph Shines
Perfect for:
| Use Case | Why Ralph Works |
|---|---|
| Framework migrations | Hundreds of files, same process |
| Increasing test coverage | TDD loop until all tests green |
| API documentation | Iteratively document all endpoints |
| Code standardization | Linting fixes across entire codebase |
Real-world example: Geoffrey Huntley ran a loop for 3 months. The result: Cursed - a complete programming language with compiler, standard library, and editor support. Autonomously developed.
An MVP for a $50,000 contract was delivered for $297 in API costs.
When Ralph is the Wrong Choice
Not every task benefits from autonomy:
- Architectural decisions - Requires human judgment
- Unclear requirements - No “done” criteria means no convergence
- Security-critical code - Authentication, payments
- Exploratory work - When you don’t know what you want yet
Best Practices
1. Define Clear Completion Criteria
❌ Bad:
"Build a todo API and make it good."
✅ Good:
"Build a REST API for todos.
- CRUD endpoints for /todos
- Input validation
- Error handling
- Tests with >80% coverage
Output <promise>COMPLETE</promise> when ALL requirements met."
2. Always Set max-iterations
# Safety net against infinite loops
/ralph-loop "..." --max-iterations 30
3. Build in Escape Hatches
After 20 iterations without progress:
- Document what's blocking
- List attempted approaches
- Suggest alternatives
- Output <promise>NEEDS HELP</promise>
4. Use a Git Directory
Every iteration auto-commits. If things go wrong: git reset --hard and restart is often faster than debugging.
The Cost Question
Transparency matters:
- API costs: 50 iterations on a large codebase = $50-100+
- Claude Code subscription: Hits usage limits faster
- Time vs. money: A developer day costs more than a $50 loop
The math works out when the alternative is manual work spanning days.
The Mindset Shift
Ralph changes how you work with AI:
Old: Guide Claude step by step New: Design prompts that converge toward correct solutions
Your role becomes prompt architect. You define success, Claude finds the path.
As Huntley puts it:
“Ralph will test you. Every time Ralph has taken a wrong direction, I haven’t blamed the tools - I’ve looked inside.”
Conclusion
The Ralph Wiggum Loop isn’t a silver bullet. But for the right tasks - clearly defined, iterative, time-intensive - it’s a game changer.
The technique shows where we’re heading: From AI as assistant to AI as autonomous colleague, completing tasks overnight while you sleep.
And when you wake up in the morning, the PR is ready for review.
Further Reading
