# Ralph Wiggum — Anthropic Official Autonomous Loop Plugin

> Official Anthropic plugin that turns Claude Code into an autonomous loop. Adds /ralph-loop and /cancel-ralph for long-running self-improving task execution.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Ralph Wiggum — Anthropic Official Autonomous Loop Plugin

## Quick Use

1. In any Claude Code session, run:
   ```
   /plugins install ralph-wiggum
   ```
2. Start a Ralph loop (auto-iterates until done):
   ```
   /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
   ```
3. Cancel mid-run:
   ```
   /cancel-ralph
   ```

> Token safety: Ralph keeps consuming tokens until it reaches `--max-iterations` or matches `--completion-promise`. Always set `--max-iterations` on first use and validate on a small task.

---

## Intro

Ralph Wiggum is the official Anthropic plugin that turns Claude Code into an autonomous, self-iterating development loop — the same pattern Boris Cherny (Claude Code's creator) uses for his longest-running tasks. Best for refactors, multi-file migrations, and "until-it-passes" TDD where you would otherwise babysit Claude over many turns.

The technique is named after Ralph Wiggum from The Simpsons — embodying persistent iteration despite setbacks. Under the hood it is a loop that re-feeds Claude its prompt + completion criteria until it emits a finish signal. Works with Claude Code 1.x and above. Setup time: under 1 minute.

---

## How Ralph Wiggum Works

A Ralph loop is structurally a `while true` that re-runs Claude Code with the same prompt file each iteration, accumulating context and self-correcting until either:

1. The model emits an explicit completion sentinel (the `--completion-promise` string), OR
2. `--max-iterations` is reached.

Boris Cherny on his personal setup page (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."

### Slash commands installed

| Command | What it does |
|---|---|
| `/ralph-loop "<prompt>" [--max-iterations N] [--completion-promise "TEXT"]` | Start an autonomous loop in the current session |
| `/cancel-ralph` | Stop the active loop |

### When to reach for it

- Multi-file refactors that need many edit-test cycles
- TDD: "make all tests pass, then output COMPLETE"
- Long migrations (e.g. "convert all class components to hooks")
- Avoid for open-ended exploration (Ralph keeps going — burns tokens)
- Avoid when verification is hard to express as a single sentinel string

### Cost discipline (must-read)

Ralph will happily burn through your token budget. Boris's safety pattern:
1. Always set `--max-iterations` (never default unlimited).
2. Make `--completion-promise` something Claude can only emit when all tests pass.
3. Start with small tasks; observe iteration count before scaling.

---

## Example: full TDD loop

```
/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
```

---

## FAQ

**Q: What is Ralph Wiggum for Claude Code?**
A: An official Anthropic-maintained Claude Code plugin that adds `/ralph-loop` and `/cancel-ralph` slash commands, letting Claude run an autonomous self-improving loop until it hits a completion sentinel or max-iterations cap.

**Q: Is Ralph Wiggum free?**
A: Yes, the plugin itself is free and open source under Anthropic's `claude-plugins-official` marketplace. You only pay for the Claude API tokens consumed during the loop.

**Q: How do I install Ralph Wiggum?**
A: Run `/plugins install ralph-wiggum` inside any Claude Code session. No additional config or marketplace registration needed.

**Q: How do I stop a runaway loop?**
A: Use `/cancel-ralph` from inside the same session, or set `--max-iterations` upfront so the loop self-terminates.

**Q: Can I use Ralph for non-coding tasks?**
A: Yes — community variants like ralph-wiggum-marketer use the same loop pattern for copy iteration. The official plugin is task-agnostic; success depends on writing a verifiable completion-promise.

---

## Source & Thanks

> Built and maintained by [Anthropic](https://github.com/anthropics) as part of the official `claude-plugins-official` marketplace. Inspired by Geoffrey Huntley's "Ralph" technique.
>
> [anthropics/claude-code · plugins/ralph-wiggum](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)

Boris Cherny credits this plugin specifically for his "very long running tasks" workflow on howborisusesclaudecode.com.


---
Source: https://tokrepo.com/en/workflows/ralph-wiggum-anthropic-official-autonomous-loop-plugin-5920075d
Author: Anthropic