You're cleaning up code quality issues in a project you inherited. Your linter flags 47 problems. The workflow looks like this:
After 30 minutes, you're frustrated. Not because Claude can't fix the errors—it can. But because you've become a manual feedback loop operator, running commands, copying output, and waiting for Claude to respond.
The question: What if Claude could run the linter, see the errors, fix them, verify the fixes worked, and continue until all 47 problems are resolved—while you go get coffee?
That's what Ralph Wiggum Loop solves.
Manual iteration overhead has three hidden costs:
Common iteration-heavy workflows where this pain appears:
These aren't edge cases—they're everyday workflows. Every developer faces iteration-heavy tasks weekly.
Rule of thumb: If you expect more than 10 iterations, Ralph Loop saves time.
Definition: Ralph Wiggum Loop is a Claude Code plugin that enables autonomous iteration—Claude Code runs a task, checks the result, identifies what needs fixing, makes corrections, and repeats until a completion condition is met, all without your intervention.
Named after: The Simpsons character Ralph Wiggum, known for cheerful persistence despite mistakes. The plugin embodies "try, fail, learn, repeat"—exactly what autonomous iteration requires.
Ralph Loop uses the Stop hook (from Lesson 15) to intercept Claude Code's normal exit behavior:
Key Components:
Created by Geoffrey Huntley in summer 2025, formalized by Boris Cherny (Anthropic Head of Claude Code) in late 2025. Real production usage includes:
Why "plugin" not "built-in": Autonomous iteration carries cost and control risks. Making it a plugin ensures users opt in deliberately, not accidentally.
You learned about four hook events in Lesson 15:
Stop Hook is a special hook that fires when Claude is about to exit (stop working).
The Pattern: Stop hook acts as a persistence layer—it won't let Claude quit until success criteria are met.
The Stop hook has access to:
When Stop hook fires, it:
Why This Works: Claude Code is stateful—it remembers the conversation. Each reinjection adds context about what failed, creating a self-correcting loop where Claude learns from previous attempts.
The --completion-promise parameter is set once and cannot be changed during runtime.
This means:
The Stop hook checks for the same exact string on every iteration using exact string matching—there's no dynamic adaptation or smart detection.
Why --max-iterations is Your Primary Safety Net: Since the completion promise uses fragile exact string matching and cannot be changed during runtime, always rely on --max-iterations as your main safety mechanism. The completion promise is a success signal, not a safety mechanism.
The Ralph Wiggum plugin is available through Claude Code plugin marketplaces. This lesson teaches the standard marketplace installation approach—no custom development required.
If you haven't already added the Anthropic plugins marketplace (from Lesson 16):
Use the interactive plugin UI:
Select "ralph-wiggum" from the list and install.
Alternative: Direct Install
After installation, the /ralph-loop and /cancel-ralph commands become available.
Test by running:
You should see usage instructions with parameter options.
Note: Installation is one-time. The plugin persists across all future Claude Code sessions.
Not every task benefits from autonomous iteration. Here's how to decide:
1. Framework Upgrades
2. Test-Driven Refactoring
3. Linting/Type Error Resolution
4. Deployment Debugging
1. Tasks Requiring Human Judgment
2. Exploratory Research
3. Creative Work (writing, design, architecture decisions)
4. Multi-Goal Tasks ("Fix bugs AND add features AND write docs")
5. Tasks Requiring External Input (waiting for API keys, user decisions, third-party approvals)
The Golden Rule: Ralph Loop excels when success is objective, verifiable, and deterministic—measurable by tools, not human judgment.
Think about your current project. What task would benefit from autonomous iteration?
Prompts to help identify:
Examples by domain:
What text signals "we're done"?
Good completion promises are:
Two approaches:
Approach 1: Use Natural Tool Output
Rely on commands naturally producing completion signals:
Approach 2: Embed Output Promise in Prompt (Recommended for reliability)
Explicitly instruct Claude to output a completion marker:
Why this works better:
More examples with embedded promises:
Best Practice: Use the embedded <promise> pattern for complex tasks where tool output might vary. Use natural tool output for simple, standard commands (linters, test runners).
Determine --max-iterations based on task complexity:
Conservative approach: Start with 20 iterations. If the loop hits the limit without completing, you can restart with a higher limit—or break the task into smaller chunks.
Template with Embedded Promise (Recommended):
Real example:
Alternative (using natural tool output):
Ralph Loop doesn't require constant attention, but checking periodically helps:
When the loop completes (or hits max iterations):
Expected Outcome: You've successfully run an autonomous iteration loop and seen how Claude self-corrects without manual feedback.
Ralph Loop can consume significant API credits. Real-world examples:
Cost Protection Rules:
1. Write Clear Task Descriptions
2. Use Embedded Promise Pattern for Reliability
Use the embedded <promise> pattern (detailed in Step 2) instead of relying on unpredictable tool output. This gives you full control over the completion signal and ensures Claude knows exactly what to output.
3. Choose Unambiguous Completion Promises
4. Provide Context in CLAUDE.md
Before running Ralph Loop, ensure CLAUDE.md includes:
Better context → fewer wasted iterations
5. Use Version Control
Before starting a loop:
If the loop goes wrong, you can revert straightforwardly.
6. Review, Don't Blindly Accept
Ralph Loop automates iteration, not judgment. Always review the final result before merging.
Cancel the loop (/cancel-ralph) if:
The Philosophy: Ralph Loop is a powerful tool, not autopilot. You remain responsible for the outcome.
Q: Can Ralph Loop run overnight while I sleep?
Technically yes, but not recommended unless:
Most users prefer checking in every 30-60 minutes.
Q: What happens if I lose internet connection during a loop?
The loop stops. Claude Code requires persistent connection. When you reconnect, you'll need to restart the loop, but Claude will see previous attempts in the conversation history.
Q: Can I run multiple Ralph Loops in parallel?
Yes, in separate Claude Code sessions (like Boris's parallel sessions pattern from Lesson 18). Each loop operates independently.
Q: How do I know if Ralph Loop is actually making progress?
Watch for:
Q: Is Ralph Loop the same as GitHub Copilot Workspace or Cursor's Agent mode?
Similar concept (autonomous iteration), different implementation:
All solve iteration fatigue, but with different architectures.
Q: Can I change the completion promise while the loop is running?
No. As explained in "How Stop Hooks Work," the --completion-promise parameter is static—set once at loop start using exact string matching. You cannot modify it during runtime or use multiple completion conditions. This is why the embedded <promise> pattern (Step 2) is critical for reliability.
Q: Can I use Ralph Loop without the plugin by manually reinjecting prompts?
Yes, but extremely tedious. The plugin automates exactly what you'd do manually: check result, decide if done, prompt Claude to continue if not. Doing this 30 times manually defeats the purpose.
Let's explore how to apply Ralph Loop to your specific workflow:
🔍 Identify Your Loop Candidates:
"Analyze my current workflow [describe your typical tasks: web dev, data analysis, DevOps, etc.]. Which tasks would benefit most from autonomous iteration using Ralph Loop? For each candidate, suggest: (1) the task description, (2) appropriate completion promise, (3) estimated max-iterations, (4) potential risks or gotchas."
What you're learning: How to recognize automation opportunities in your own work, not generic examples.
🎯 Design Safety Guardrails:
"I want to use Ralph Loop for [YOUR SPECIFIC TASK]. Help me design safety guardrails: (1) What's a reasonable --max-iterations limit? (2) What could go wrong and how do I detect it early? (3) What should I put in CLAUDE.md to give Claude the context it needs? (4) How do I test this on a small scope before running on the full codebase?"
What you're learning: Risk assessment and incremental validation—critical skills for production AI usage.
🚀 Troubleshoot a Stuck Loop:
"I'm running a Ralph Loop to [YOUR TASK], but after 8 iterations, Claude keeps hitting the same error: [DESCRIBE ERROR]. The completion promise is '[YOUR PROMISE]'. Why might Claude be stuck? How can I help it get unstuck without canceling the loop and starting over?"
What you're learning: Debugging autonomous systems—recognizing when AI needs human intervention to break out of local optima.
Workflow Impact:
Ralph Loop demonstrates autonomous execution—one of the core capabilities of Digital FTEs. When you package skills, specs, and autonomous iteration into an agent, you create systems that:
This is the pattern behind sellable AI agents:
Paradigm Connection:
You learned in Chapter 1 that AI shifts work from "executing" to "orchestrating." Ralph Loop embodies this:
Real-World Context:
The same pattern powers production AI employees:
Mastering Ralph Loop teaches you the mechanics of autonomous iteration—essential for building and selling Digital FTEs.