Ralph Wiggum — Anthropic Official Autonomous Loop Plugin

What Is the Ralph Wiggum Plugin

The Ralph Wiggum plugin is the official Anthropic-maintained Claude Code extension that transforms a normal interactive coding session into an autonomous, self-iterating loop. After running /plugins install ralph-wiggum you gain two slash commands: /ralph-loop to start an unattended run and /cancel-ralph to abort it. The plugin ships from Anthropic's claude-plugins-official marketplace, so installation requires zero marketplace registration and zero extra configuration. Setup time on a fresh Claude Code install is under 60 seconds.

The technique is named after Ralph Wiggum from The Simpsons, embodying persistent iteration despite setbacks. It is also the same pattern Boris Cherny, the creator of Claude Code, calls out on his personal howborisusesclaudecode.com page as his preferred approach for "very long running tasks." The Ralph loop is structurally a while true that re-feeds Claude its prompt and completion criteria each iteration, accumulating context and self-correcting until either an explicit completion sentinel fires or the --max-iterations cap is reached.

For a single command flow that mirrors the same one-shot ergonomics, see the related TokRepo entry commit-push-pr one-shot slash command.

How the Ralph Loop Works Under the Hood

A Ralph loop has three structural pieces: a prompt file, a completion-promise sentinel string, and an iteration cap. On each tick the plugin re-runs Claude Code with the same prompt, lets the model edit, test, and reason, and then checks the model's output for the sentinel. If the sentinel matches, Ralph exits cleanly. If --max-iterations N is reached first, Ralph exits with a non-success state so you can inspect the partial result.

This architecture matters for two reasons. First, the loop accumulates context across iterations, so the model can self-correct after failed test runs without losing state. Second, the explicit sentinel decouples "done" from heuristic guesses; the model only emits the promise when its own verification step (e.g. npm test exit code 0) passes. Boris Cherny describes the same pattern in his own words on howborisusesclaudecode.com:

"For very long running tasks, I either prompt Claude to verify its work with a background agent, use an agent-stop hook, or use the Ralph Wiggin plugin for autonomous looping."

The plugin currently supports Claude Code 1.x and above. It plays nicely alongside hook-based schedulers; if you also need a recurring local task runner, pair it with loop, the Boris-style local recurring task scheduler.

Slash Commands Installed by Ralph Wiggum

The plugin registers exactly two commands inside any Claude Code session, summarized below. Both are scoped to the current session, so multiple terminals stay isolated.

The full canonical invocation from the official skill template is:

/ralph-loop "Build a REST API for todos. Requirements: CRUD ops, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50

Note the <promise>COMPLETE</promise> wrapper inside the prompt. This is a contract: Claude only emits the wrapper when its self-verification passes, and Ralph only matches when the literal COMPLETE string appears in output. Both halves must agree, which is the single most important habit for safe autonomous loops.

When to Reach for Ralph (and When Not To)

Ralph is a power tool, not a default. The official skill identifies four high-fit and two anti-fit scenarios.

Use Ralph for:

1. Multi-file refactors that need many edit-test cycles (e.g. "convert all class components to React hooks").
2. Test-driven development with a clean exit criterion ("make all tests pass, then output COMPLETE").
3. Long migrations across dozens of files where babysitting the model wastes wall-clock time.
4. Repeatable codemod-style transforms with a deterministic verifier such as eslint --max-warnings 0 or pytest -x.

Avoid Ralph for:

1. Open-ended exploration. Ralph keeps going until it hits the cap, so vague "explore options" prompts burn tokens with no exit.
2. Tasks where verification is hard to express as a single sentinel string. If you cannot write a 1-line check, write a sub-agent first; see build-validator CI validation subagent for a sentinel-friendly verifier pattern.

Cost Discipline: Ralph Will Burn Tokens If You Let It

The single biggest failure mode is unbounded token spend. Ralph re-feeds the full conversation each iteration, so token costs grow super-linearly with iteration count. The official safety pattern from the plugin documentation is:

1. Always set --max-iterations explicitly on the first run; never rely on a default. Start with 10 to 30 for a small task and scale up only after observing the typical iteration count.
2. Make the completion-promise verifiable. Pin it to a real check, like <promise>RALPH_COMPLETE</promise> emitted only after npm test && npm run lint both exit zero.
3. Validate on a small task first. Run on a 2-file change before unleashing on a 200-file migration; you will discover sentinel typos and prompt ambiguities cheaply.
4. Pair Ralph with token telemetry. Watch real-time spend with ccusage, the real-time token cost tracker for Claude Code so you can /cancel-ralph before a runaway loop drains the budget.

According to Anthropic's own pricing page, Claude Sonnet runs at $3 per million input tokens and $15 per million output tokens; a 50-iteration Ralph loop on a medium-sized refactor can easily process several million tokens, so even a 10 percent reduction in iterations is meaningful.

Step-by-Step: Your First Ralph Loop

The canonical first-run, taken straight from the skill template, has exactly three steps. This is the verified, no-extrapolation flow:

1. In any Claude Code session, run:

```

/plugins install ralph-wiggum

```

1. Start a Ralph loop that auto-iterates until the sentinel fires:

```

/ralph-loop "Build a REST API for todos. Requirements: CRUD ops, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50

```

1. Cancel mid-run if needed:

```

/cancel-ralph

```

For a more realistic full-TDD scenario, the plugin documentation provides a parseDuration example. The prompt forces npm test and npm run lint as gates before the sentinel can fire:

/ralph-loop "
Implement a TypeScript function 'parseDuration(input: string): number' that
parses strings like '2h30m', '1d', '45s' into milliseconds.

Requirements:
1. Run npm test after each iteration
2. Fix all failing tests
3. When all tests pass AND npm run lint is clean, output:
   <promise>RALPH_COMPLETE</promise>
" --completion-promise "RALPH_COMPLETE" --max-iterations 30

This pattern is the foundation of "agentic TDD." The model is forced to keep the loop alive until the verifier produces a green build, then it must explicitly emit the sentinel. There is no way to fake completion because the sentinel string is gated behind tool output you can audit in the transcript.

Comparing Ralph to Other Anthropic Autonomous Patterns

Ralph is one of three documented Anthropic patterns for long-running work. Each has a distinct trade-off profile.

For an even broader orchestration pattern that runs many agents in parallel rather than one self-iterating agent, see claude-flow multi-agent orchestration. For a one-command end-to-end workflow with built-in verification and simplification passes, the go-verify-simplify PR command covers the non-autonomous side of the same problem.

Beyond Code: Non-Coding Use Cases

The plugin is task-agnostic. Any task with a verifiable completion criterion can drive a Ralph loop. Community variants such as ralph-wiggum-marketer use the same loop pattern for copy iteration, regenerating headlines until they pass a checklist sentinel. The official plugin remains a generic primitive; success depends on writing a completion-promise that is impossible to emit without satisfying the goal.

A practical pattern: have Claude write a 1-line bash check, then have it run that check via a tool call, then have it emit the sentinel only when the check exits zero. As long as the sentinel is observable in the transcript and the check is real, autonomous mode is safe.

Source, Provenance, and Thanks

Ralph Wiggum is built and maintained by Anthropic as part of the official claude-plugins-official marketplace. The plugin source is hosted under the anthropics/claude-code GitHub organization. The naming and core technique are inspired by Geoffrey Huntley's earlier "Ralph" loop write-up; Anthropic packaged it into a first-party plugin so users do not have to maintain bespoke loop scripts. Boris Cherny credits this exact plugin for his "very long running tasks" workflow on his personal Claude Code page.

For TokRepo readers who want to keep building on the Anthropic-official surface, two adjacent assets pair well: code-simplifier, the official Anthropic cleanup subagent and the SuperClaude workflow framework for Claude Code. Combined with Ralph, they form a tight "loop, simplify, verify" stack you can run before every PR.