What Is Claude Ralph Loop | How to Use the Autonomous Iteration Plugin

What Is Ralph Loop — The "Undying Loop" That Intercepts Termination via Stop Hook

Ralph Loop is an extremely simple pattern proposed by Geoffrey Huntley in "everything is a ralph loop". At its core, it is just a single while loop and LLM tokens — the idea being to feed the agent the same prompt indefinitely, using the filesystem as memory storage. In the Anthropic official implementation, this is achieved using Claude Code's Stop Hook. The moment Claude decides a task is finished and attempts to exit, the Hook blocks that exit and re-injects the original prompt, generating an iterative improvement cycle without human intervention. The name "Ralph" comes from the image of Simpsons character Ralph Wiggum looping on a roller coaster, used on the cover of the original article — symbolizing the philosophy that "things take shape as long as you keep looping them." Huntley himself describes the core idea as: "Software is like pottery clay — you can always put it back on the wheel as many times as needed." (Source: ghuntley.com/loop)

Ralph Loop as an Official Plugin — Install in One Line with /plugin install ralph-wiggum

The commands and syntax in this section are based on the official README as of May 2026. Marketplace plugins can be revised quickly, so always verify the latest syntax against the plugin listing and official README after installation.

In 2026, Anthropic incorporated Ralph Loop into the official marketplace claude-plugins-official as the ralph-wiggum plugin. After launching Claude Code, you can install it in one line either from the plugin listing or by running the following command:

# Install the ralph-wiggum plugin from the official marketplace
/plugin install ralph-wiggum@claude-plugins-official

# Activate after installation (/ralph-loop and /cancel-ralph become available)
/reload-plugins

After installation, activate with /reload-plugins, and you will have access to two commands: /ralph-loop and /cancel-ralph. The plugin itself is extracted to ~/.claude/plugins/cache/claude-plugins-official/ralph-wiggum/<hash>/hooks/hooks.json, with only the Stop Hook launch command registered as a handler. On Windows, the official README explicitly specifies using Git/bin/bash.exe (wrapper version) bundled with Git for Windows — there is a known issue where Git/usr/bin/bash.exe (MinGW version) fails to launch the Hook at all, so the default settings work fine. With the plugin format, developers no longer need to write their own Stop Hook YAML, significantly lowering the barrier to adoption. (Source: claude-plugins-official ralph-loop README)

How to Use the /ralph-loop Command — Always Pair --max-iterations with --completion-promise

The basic syntax for the /ralph-loop command is /ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>". Of the three elements, the prompt is the "instruction sheet" Claude re-reads on every iteration, so it must explicitly include a clear completion criterion and the token to output upon completion. For example, it is recommended to pack all three elements — requirements, test coverage target, and completion token — into a single string, as shown below:

# Always specify all three elements: prompt + --completion-promise + --max-iterations
/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests with coverage > 80%. Output <promise>COMPLETE</promise> when done." \
  --completion-promise "COMPLETE" \
  --max-iterations 50

When --max-iterations is omitted, execution is unlimited, so always specify a value of around 10–20 on the first run to prevent runaway behavior. Since --completion-promise uses exact-match evaluation, there is no tolerance for variation. In the prompt, explicitly state "output <promise>COMPLETE</promise> only on success" and tie the completion condition to something like all tests passing or zero lint errors to reduce the risk of accidents. If --max-iterations is reached without satisfying the exit condition, Claude is designed to stop and leave behind "the reason it could not proceed," "what it tried," and "alternative approaches," allowing a human to take over from where it left off. (Source: ralph-loop plugin specification)

Anatomy of the Internal Mechanism — 6 Steps by Which the Stop Hook Intercepts Termination

The internal operation of Ralph Loop can be broken down into 6 steps.

1. The user launches /ralph-loop and passes a prompt to Claude.
2. Claude calls tools as usual, writes code, runs tests, and observes results.
3. Claude determines the task is complete and attempts to end the session.
4. The Stop Hook intercepts that termination attempt and blocks the exit.
5. The Hook re-injects the original prompt, and Claude re-evaluates the situation by looking at the files modified during the previous run and the git change history.
6. Steps 2–5 repeat until the completion-promise token appears in Claude's output or the --max-iterations limit is reached.

The key points are that the prompt does not change between iterations at all, and that state is persisted to files and git history rather than to conversation history. This allows long-running tasks to be executed without the context window ballooning. As Huntley puts it, "failure is deterministically bad and informative" — a deterministic failure like a failing test clearly functions as "something to fix" when Claude re-reads it on the next iteration, making a self-correcting feedback loop a natural outcome.

Prompt Design Best Practices — Pack Completion Criteria, Phase Goals, and Self-Correction Steps into One String

The effectiveness of Ralph Loop depends heavily on the quality of the prompt.

1. Write completion criteria in a verifiable form. Vague instructions like "make it good" make it impossible for iterations to converge. Break down conditions into ones Claude can verify by running tests or using grep — for example: All CRUD endpoints working, Tests passing (coverage > 80%), README with API docs.
2. Explicitly state phase goals. Divide the work into stages such as "Phase 1: User authentication (JWT implementation + tests), Phase 2: Product catalog (list, search + tests), Phase 3: Shopping cart (add, remove + tests)," and instruct Claude to output the completion token once everything is in place.
3. Embed a self-correction process in TDD format. Building the following flow into the prompt stabilizes behavior across iterations: "Write a failing test → implement → run tests → debug on failure → refactor → repeat until all green → output COMPLETE."
4. Include safety language. Adding "if incomplete after 15 iterations, document the cause blocking progress, what was tried, and alternatives, then stop" ensures meaningful records are left in the event of a runaway.

Safety Mechanisms to Prevent Runaway — --max-iterations Is Mandatory; Role of /cancel-ralph

While Ralph Loop is convenient, misconfiguration can cause it to consume tokens indefinitely. The primary safety mechanism is --max-iterations, which the official README explicitly describes as the "primary control mechanism" and a required option. Since --completion-promise uses exact-match evaluation, it is vulnerable to any variation — if Claude outputs Complete. instead of COMPLETE as written in the prompt, the exit condition fails and the loop runs forever. --max-iterations is what compensates for this: keep it at 10–20 on the first run, and even once you are familiar with the tool, cap it at around 50 for safety. To stop a loop while it is running, call /cancel-ralph from a separate session to interrupt the in-progress loop. For additional layers of defense, enabling cost alerts on the Claude Code subscription itself helps avoid unexpected monthly consumption even on the Claude Max 20x plan. When running /ralph-loop on a production repository, always create a working branch and set up a safety net with git push before starting — this is an iron rule. (Source: Geoffrey Huntley's safety remarks)

Tasks It Suits and Tasks It Does Not — Great for TDD Greenfield, Never Use It for Production Debugging

Ralph Loop is not a universal tool; there are clear cases where it works well and cases where it does not.

Cases where it works well:

1. Tasks with clear success criteria. When a goal can be evaluated mechanically — such as all tests passing or zero lint errors — effectiveness is maximized.
2. Tasks that inherently require iterative improvement. It pairs exceptionally well with TDD (test-driven development) workflows that cycle through red (failing tests) → green (tests passing) → refactor.
3. Greenfield projects (new projects with no existing code). Without needing to worry about the impact on an existing codebase, the damage from any runaway is minimized.
4. Automating repetitive work. Examples include setting up CI-verifiable scripts or generating large volumes of test fixtures.

Cases where it does not work well:

1. Design decisions requiring human judgment. UI tone and manner or architecture selection will not converge in a loop.
2. One-shot operations. Wrapping a single-run task in a loop is over-engineering.
3. Tasks with unclear success criteria. If the completion-promise cannot be evaluated mechanically, the loop breaks down from the start.
4. Debugging production environments. Allowing iterative execution against production resources with hard-to-predict side effects is a recipe for accidents.

Track Record and Cost-Effectiveness — A Case Study: $50k Worth of Code Produced for $297

The track record Geoffrey Huntley has made public illustrates the cost-effectiveness of Ralph Loop clearly. At a hackathon hosted by Y Combinator, he reportedly generated 6 repositories overnight, including fully working applications. There is also a case where a contract worth $50k was completed for approximately $297 in Claude API costs, demonstrating that replacing human manual labor with Claude can produce orders-of-magnitude productivity gains. A similar story involves building a new programming language called "cursed" single-handedly in 3 months — the longer and more persistently iterative a task is, the more Ralph Loop's true value emerges. These results are not necessarily reproducible by everyone; they presuppose that the advocate himself is an expert at prompt design. However, the underlying idea of "replacing the time a human would spend repeating the same thing with a loop" is applicable to anyone. Anthropic's decision to incorporate this plugin into the official marketplace is understood to be an effort to provide a safe entry point for developers to try Ralph Loop, informed by these success stories. (Source: ghuntley.com/loop)

Practical Steps for Integrating Ralph Loop into Claude Code

Finally, here is a concrete set of steps for integrating Ralph Loop into Claude Code right now.

1. Update Claude Code to the latest version, open /plugin marketplace, and confirm that claude-plugins-official is listed.

2. Run /plugin install ralph-wiggum@claude-plugins-official to install, then activate with /reload-plugins.

3. Create a working git branch and confirm that git status shows a clean state.

4. Do a trial run with a small task. For example, you can copy and run the following command as-is:

   /ralph-loop "Fix all failures in ./scripts/lint.sh to zero. When done, output <promise>COMPLETE</promise>" \
     --completion-promise "COMPLETE" \
     --max-iterations 10
   

5. After completion or reaching the iteration limit, always have a human review the changes with git diff to confirm no unintended modifications were mixed in before committing.

6. Based on that success, gradually increase the scope of tasks, and once you can run something like "implement one new feature test-first" over 30–50 iterations, Ralph Loop will become an indispensable tool.

Two important cautions: never run it directly on the main branch of a production repository, and always check the billing status before leaving it unattended for extended periods. (Source: claude-plugins-official ralph-loop)