The Ralph Wiggum loop: run an agent over and over until the tests go green
TL;DR
The Ralph Wiggum loop (named after the Simpsons character) runs an AI agent in a loop on a fixed prompt, checks the result with tests/lint/type-checks after each pass, and stops only when the checks pass or an iteration cap is hit. The harness decides when it’s done — not the model.
The mechanism
for i in $(seq 1 20); do
claude -p "$(cat PROMPT.md)"
npm test && npm run lint && break # a check that can't lie
done- State lives in the repo: each pass starts fresh and builds on what’s saved to disk.
- Anthropic ships a Ralph Wiggum plugin for Claude Code that uses a Stop Hook instead of a bash loop — easier, but it hides the mechanics.
When it fits — and when it doesn’t
| Good fit | Poor fit |
|---|---|
| Refactors, migrations, cleanup | Exploratory work without acceptance criteria |
| Fixing until the test suite is green | UX design, product decisions |
| Following a fixed spec | Requirements that change mid-run |
Mandatory guardrails
- Cap iterations and time to control token spend.
- Keep the spec fixed for the whole loop so the agent doesn’t drift.
- Make “done” an executable check, not a question like “are you finished?”.
- Keep logs and diffs per pass; prefer small changes.
- Run on a separate branch or sandbox and review before merging.
Further reading: The Ralph Wiggum Loop (DreamHost) · Self-improving coding agents (Addy Osmani)