What is the Ralph loop?
A Ralph loop is an outer loop around a coding agent's own agent loop. The inner loop is the agent reading, editing and running tools until it thinks it is finished. The outer loop ignores that opinion and starts the agent again with the same instructions. Geoffrey Huntley, who named it, puts it bluntly: "Ralph is a technique. In its purest form, Ralph is a Bash loop."
while :; do cat PROMPT.md | claude-code ; done
That is the loop as it appears in Huntley's
original post. Later write-ups use the
current non-interactive invocation, claude -p, and add an iteration counter. The prompt file
points at a set of specifications and a plan; each pass picks the most important unfinished item, implements
it, runs the checks, updates the plan and commits.
Where did the Ralph Wiggum technique come from?
Huntley published "Ralph Wiggum as a 'software engineer'" on 14 July 2025. HumanLayer's history of the technique dates his first public presentation of it to a meetup on 19 June 2025, and records that Huntley later used Ralph to build cursed, an experimental programming language, in 2025. The name is the Simpsons character: individually clumsy attempts that still get somewhere through persistence.
In December 2025 Anthropic added a ralph-wiggum plugin to its claude-code repository, credited to Huntley's technique. Search interest followed: "ralph loop" draws about 5,400 US searches a month and "ralph wiggum loop" about 2,400 (Google Ads data, November 2026).
Why restart the agent instead of letting it keep going?
Because context degrades. Every tool call and every file read stays in the window, and quality drops as the window fills; Huntley notes this explicitly. A fresh process per pass resets that. The state that matters is kept outside the model, where it cannot be summarised away:
- Specifications. One file per topic, written in an interactive session before the loop starts.
- A plan file. Huntley's
fix_plan.md: the list the agent picks from and updates each pass. - Steering files. An
AGENTS.mdorCLAUDE.mdwith build and test commands and the lessons from earlier failures. - Git history. A commit per pass gives the next pass, and the reviewer, a record of what changed.
This is the same discipline that makes any long-running agent reliable, applied crudely: short runs, state in durable storage, a fixed set of files loaded every time. For the general mechanics, see how agentic loops work and what should stop them.
How do teams run a Ralph loop with coding agents?
There are three common shapes. They differ mainly in whether each pass gets a fresh context.
| Variant | How it works | Context | What stops it | Best for |
|---|---|---|---|---|
| Bash loop (original) | A shell while loop pipes PROMPT.md into the agent in non-interactive mode | Fresh context every pass | Whatever you add: an iteration counter, a completion string, Ctrl-C | Closest to Huntley's design |
| Claude Code ralph-wiggum plugin | /ralph-loop command; a Stop hook blocks exit and re-feeds the same prompt | One session; prior work visible through files and git | --completion-promise phrase or --max-iterations (default unlimited) | Quick start inside Claude Code |
| Harness-level goal loop | An evaluator checks a stated goal each time the agent tries to stop | One session | Goal met or turn cap reached | Tasks with a measurable finish line |
The plugin is the easy entry point and also the most debated. Its README says the completion promise is an
exact string match, so it cannot express "done" and "blocked" as separate outcomes, and tells users to rely on
--max-iterations as the primary safety mechanism. HumanLayer's critique is structural: running
inside one session misses Ralph's point of carving work into independent context windows. Steve Kinney's
practitioner guide
makes the same distinction and recommends the shell form with a cap and a completion string.
Teams that get value from it treat the loop as the execution phase only. Discovery and specification happen interactively first. The loop then works through a plan whose items are each small enough to finish and verify in one pass.
What are the risks, and which guardrails fix them?
Huntley is candid about the limits. He describes Ralph as best for bootstrapping greenfield projects, "with the expectation you'll get 90% done", says he would not use it in an existing codebase, and states that "there is no way this is possible without senior expertise guiding Ralph". Repeated implementations of the same feature are, in his words, its Achilles' heel. The guardrails below map each known failure to a control.
| Risk | Guardrail |
|---|---|
| Runaway spend | A hard iteration cap on every run; start small and raise it once the loop converges |
| False "done" | Completion decided by tests or a checklist the agent cannot edit, not by the agent's own claim |
| Duplicate or placeholder implementations | Prompt tells the agent to search before writing and forbids stubs; review catches the rest |
| Thrashing on a large task | One item from the plan file per pass; break specs into units a single pass can finish |
| Stuck on an impossible task | A stuck signal the agent emits after documenting the blocker, which ends the loop |
| Damage outside the repo | Run in a container or sandbox with no production credentials; skipped permission prompts only inside that boundary |
| Unreviewable history | Commit per pass on a dedicated branch; merge through the normal pull request process |
The guardrail that matters most is backpressure: mechanical checks that reject a bad pass without a human. Huntley recommends running tests for every unit changed and adding type checkers or static analysis, especially in dynamically typed languages. Anthropic's README draws the same line from the other side. It lists well-defined tasks with automatic verification and greenfield work as good fits, and tasks needing human judgment, unclear success criteria or production debugging as poor ones.
Running unattended usually means skipping permission prompts. Do that only inside a container or sandbox with no production credentials, so a confused pass can damage a branch and nothing else. The cost and oversight trade-offs of that choice are covered in what autonomy actually costs.
Should your team use it?
Use a Ralph loop when three things are true: the work is specified in files, every item has a check a machine can run, and the output lands on a branch someone will review. Prototypes, greenfield services and mechanical migrations with strong test coverage fit. Ambiguous product work, security-sensitive code and anything touching production do not.
Decision rule: write the iteration cap and the test command before you write the prompt. If either is hard to write, the task needs a human in an interactive session, not a loop.
Related questions
Frequently asked questions
What is the Ralph loop?
The Ralph loop, or Ralph Wiggum technique, is a way of running an AI coding agent unattended: a shell loop feeds the same prompt file to the agent over and over, the agent does one piece of work per pass, commits it and exits, and the next pass starts with a fresh context. Progress is kept in files and git rather than in the conversation. Geoffrey Huntley described it in July 2025.
Why is it called Ralph Wiggum?
It is named after the Simpsons character. Anthropic's plugin README describes the name as embodying persistent iteration despite setbacks; Huntley calls the technique "deterministically bad in an undeterministic world". The joke is that each individual attempt can be clumsy, and the loop still gets there if something checks the work.
How do you run a Ralph loop with Claude Code?
Two ways. The original is a shell loop that pipes a prompt file into the agent in non-interactive mode on every pass, so each pass gets a fresh context. Anthropic also ships a ralph-wiggum plugin in its claude-code repository that adds a /ralph-loop command: a Stop hook blocks the session from ending and feeds the same prompt back until a completion phrase appears or --max-iterations is reached. Always set --max-iterations; the README says its default is unlimited.
Is the Ralph loop safe to use on an existing codebase?
Huntley himself says he would not use it in an existing codebase and describes it as best for bootstrapping greenfield projects to roughly 90 percent. Teams that use it on existing code keep it to narrow, testable tasks on a branch, with commits reviewed like any pull request.
Is a Ralph loop a form of recursive self-improvement?
No. A Ralph loop repeats a task with a fixed model and a prompt a human edits; the agent improves the codebase, not itself. Recursive self-improvement is a separate topic, covered in our recursive self-improvement explainer.
Sources
- Geoffrey Huntley, Ralph Wiggum as a "software engineer" (14 July 2025, updated 19 February 2026).
- HumanLayer, A brief history of Ralph.
- Anthropic, Ralph Wiggum plugin README (claude-code repository).
- Steve Kinney, Entering the mind of Ralph Wiggum (31 March 2026, updated 14 September 2026).
- Andrew Zigler, Inventing the Ralph Wiggum loop (Dev Interrupted, 13 January 2026).