The Ralph Wiggum Technique: Run Claude Code Autonomously for Hours

You write a prompt. Claude works for a bit. Then it stops. "I've completed the implementation," it announces proudly.

You look at the result. It's 60% done.

So you re-prompt. Claude works some more. Stops again. "The feature is now complete."

Still not done.

What if Claude just... kept going? What if it iterated on its own work until the task was genuinely finished - not when it thought it was done, but when your tests actually pass?

That's exactly what the Ralph Wiggum technique enables. And developers are losing their minds over it.

What is the Ralph Wiggum plugin?

The Ralph Wiggum plugin is an official Anthropic Claude Code plugin that creates autonomous development loops. Instead of Claude stopping after a single attempt, Ralph keeps Claude working on the same task - iteration after iteration - until it genuinely succeeds.

The name comes from The Simpsons character Ralph Wiggum, embodying a simple philosophy: persistent iteration despite setbacks. Keep trying until you get it right.

Here's the core command:

/ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --max-iterations 10 --completion-promise "FIXED"

The idea is to keep iterating and hopefully converge on a defined goal. The <promise> tag pattern gives Claude a clear signal for when to output the completion marker.

When you run this:

1. Claude attempts the fix
2. When Claude thinks it's "done" and tries to exit, a Stop hook intercepts
3. The hook checks: did Claude output the completion promise ("FIXED")?
4. If not, the original prompt is re-injected with updated context
5. Claude sees its own previous work (modified files, git history)
6. It continues iterating until the promise appears in the output

The key insight: Each iteration isn't starting fresh. Claude sees what it built in the last round. It reviews its own code, notices what's broken, and fixes it. The loop creates a self-correcting feedback system.

How it actually works

The technical mechanism is surprisingly elegant. Ralph Wiggum uses Claude Code's Stop hook feature - a way to intercept when Claude tries to end a session.

Here's the flow:

You: /ralph-loop "Add auth to admin panel. Output <promise>DONE</promise> when tests pass." --max-iterations 20 --completion-promise "DONE"

[Iteration 1]
Claude: *writes auth logic, tests, middleware*
Claude: "Authentication implemented."
Stop hook: *Checks output for "DONE" - not found*
Stop hook: "Continue working."

[Iteration 2]
Claude: *sees failing tests, reviews own code*
Claude: "Found issue with session handling. Fixing..."
Stop hook: *Checks output for "DONE" - not found*
Stop hook: "Keep going."

[Iteration 3]
Claude: *fixes edge case, runs tests*
Claude: "All tests passing. <promise>DONE</promise>"
Stop hook: *Found "DONE" in output*
Stop hook: "OK, you can exit now."

The --completion-promise parameter defines what "done" actually means. By embedding it in a <promise> tag within your prompt, you give Claude a clear signal for when to output the marker. The hook simply checks if that string appears in Claude's response.

When Ralph Wiggum excels

The technique shines for specific types of work:

Large refactors

Migrating from one framework to another. Updating hundreds of files to use a new API. Converting class components to hooks. These are tasks where Claude needs multiple passes to get everything right.

/ralph-loop "Convert all class components to functional components with hooks. Output <promise>MIGRATED</promise> when npm run typecheck passes." \
  --max-iterations 30 \
  --completion-promise "MIGRATED"

Test-driven development

Write failing tests first, then let Ralph iterate until they pass:

/ralph-loop "Implement the checkout flow to make all tests in checkout.test.ts pass. Output <promise>TESTS_PASS</promise> when done." \
  --max-iterations 25 \
  --completion-promise "TESTS_PASS"

Batch operations

Documentation generation, code standardization, adding TypeScript types across a codebase - repetitive work that benefits from iteration.

Greenfield features with clear specs

When you have a well-defined feature and automatic verification (tests, linter, build), Ralph can build it incrementally.

When NOT to use it

Ralph Wiggum isn't a magic solution for everything:

Ambiguous requirements - If you can't define objective success criteria, Ralph can't know when to stop.

Architectural decisions - Choosing between microservices vs monolith isn't something to iterate on blindly.

Security-critical code - Authentication, encryption, payment processing - these need human review, not autonomous iteration.

Exploratory work - "Figure out why the app is slow" isn't a good Ralph task. You need human judgment to interpret results.

Tasks requiring human judgment - Design decisions, UX choices, business logic edge cases - keep humans in the loop.

Real results from the community

The Ralph Wiggum technique has produced some impressive outcomes:

Geoffrey Huntley's programming language: A 3-month continuous loop built "Cursed" - a complete programming language with Gen Z keywords. Yes, really.

YC hackathon teams: Shipped 6+ repositories overnight for approximately $297 in API costs. Multiple complete projects running autonomously while the humans slept.

Integration test optimization: One developer used Ralph to refactor tests, reducing runtime from 4 minutes to 2 seconds.

The common thread: well-defined tasks with automatic verification running for extended periods.

Cost considerations

Let's be real about token usage. Autonomous loops consume tokens rapidly.

A typical 50-iteration loop on a medium-sized codebase might cost $50-100+ in API usage. The --max-iterations flag isn't just a safety mechanism - it's cost control.

Best practices:

• Start with lower iteration limits (10-20) for new tasks
• Scale up once you understand the token consumption pattern
• Use specific completion criteria to exit early when possible
• Monitor cost vs. value - a $100 loop that saves 20 hours of work is worth it

Getting started

If you're using Claude Code, here's how to try Ralph Wiggum:

1. Install the plugin

Ralph Wiggum is an official Anthropic plugin. First, add Anthropic's official plugin marketplace, then install the plugin from within Claude Code:

/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-plugins-official

You can also cancel an active loop at any time with /cancel-ralph.

2. Start simple

Begin with a small, well-defined task:

/ralph-loop "Fix all ESLint errors in src/. Output <promise>LINT_CLEAN</promise> when npm run lint passes." \
  --max-iterations 10 \
  --completion-promise "LINT_CLEAN"

3. Define clear success criteria

Your --completion-promise should be:

• A simple, unique string (like "DONE", "FIXED", "COMPLETE")
• Embedded in your prompt using <promise>YOUR_MARKER</promise> syntax
• Something Claude will only output when the actual goal is achieved

4. Use with version control

Always run Ralph loops in a git-tracked directory. If something goes wrong, you can revert. Each iteration adds to git history, giving you a clear trail of what changed.

The philosophy behind it

Ralph Wiggum inverts the typical AI coding workflow. Instead of:

1. Prompt → Claude works → Output → Human reviews → Repeat

You get:

1. Prompt + success criteria → Claude loops autonomously → Human reviews final result

The technique treats failures as learning data. Each failed attempt tells Claude something about what doesn't work. Over iterations, the solution converges toward success.

This philosophy - that persistent iteration beats perfect first attempts - feels counterintuitive. We're trained to think AI should "get it right" immediately. But the reality of complex coding tasks is messier. Sometimes you need multiple passes. Sometimes you need to see what's broken before you can fix it.

Ralph Wiggum embraces that reality.

What this means for development workflows

The Ralph Wiggum technique is part of a broader shift in how we work with AI coding assistants:

From interactive to autonomous: Instead of babysitting every step, you define the goal and let the AI iterate toward it.

From single-shot to iterative: Accept that complex tasks take multiple attempts, and build that into the workflow.

From human-paced to machine-paced: An overnight loop can accomplish what would take a human days of focused work.

For teams using Claude Code heavily, Ralph Wiggum unlocks a new category of tasks - the ones too tedious for humans but too complex for single prompts.

A note on Opus 4.5

One thing worth mentioning: with Opus 4.5, the Ralph Wiggum technique is becoming less necessary for many tasks. As savage-bits noted on Reddit: Opus 4.5 is remarkably good at following a plan, and compaction (context management) has greatly improved.

These enhancements mean Claude is better at completing complex tasks in fewer iterations - sometimes even in a single pass. The model's improved ability to maintain context and execute multi-step plans reduces the need for forced iteration loops.

That said, Ralph Wiggum still shines for genuinely large refactors, overnight batch operations, and tasks where you want explicit iteration controls. It's a powerful technique to have in your toolkit, even if you find yourself reaching for it less often with newer models.