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.
Most uses of AI coding share the same failure: the agent does one pass, declares it done, but the tests are still red. The Ralph Wiggum loop (named after the Simpsons character) handles this in an almost absurdly simple way: run the agent in a loop with a fixed prompt, check with tests/lint/type-check after each pass, and stop only when the checks pass or an iteration limit is hit. "Done" is decided by the harness, not claimed by 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 iteration starts fresh, based on what's been saved to disk (code, note files, git history).
- Anthropic has a Ralph Wiggum plugin for Claude Code that uses a Stop hook instead of a bash loop: more convenient, but it hides the underlying mechanism.
Why it works
- It shifts the burden from "trusting the model's word" to "trusting command results": passing tests are objective evidence.
- It exploits iteration: each pass the agent sees the latest error and keeps fixing, like a developer's run–fix–run.
- Fresh context every iteration: avoids the context bloating and "drifting" over time.
When it fits, when it doesn't
| Fits | Doesn't fit |
|---|---|
| Refactors, migrations, code cleanup | Exploratory work with no acceptance criteria |
| Fixing until the test suite is green | UX design, product decisions |
| Following a fixed spec | Requirements still changing mid-way |
Mandatory guardrails
- Limit iterations and time to control token cost; an unbounded loop is the fastest route to a surprise bill.
- A fixed spec throughout the loop so the agent doesn't drift.
- Completion criteria are runnable commands, not the question "are you done?".
- Keep logs and diffs per iteration; prefer small changes.
- Run on a separate branch or in a sandbox, and review before merging.
Common traps
- Making tests green by deleting tests: protect test files (read-only) or check the test count doesn't drop.
- Stuck on the same error: if 3–4 consecutive iterations make no progress, stop and have a human look.
- A vague spec: the loop only amplifies vagueness; write clear success criteria first.
How to apply it
- Dev: start with a small migration that has good tests; set a limit of 10–20 iterations.
- Tech Lead: require PRs produced by a loop to include the iteration log and check results.
- PM: estimate cost as maximum iterations × cost per iteration, then add a safety margin.