Ralph Wiggum Plugin for Claude Code: Install, Commands, and Stop Hook Loop Guide

If you use Claude Code for real engineering work, you have probably seen the annoying failure mode: Claude changes a few files, says "I'm done," but the tests are still failing, the build is broken, or the original acceptance criteria were only half-finished. You end up babysitting the agent with prompts like "continue," "run the tests again," or "fix the remaining errors."

The Ralph Wiggum Plugin is designed for exactly this problem. It turns a normal one-shot Claude Code conversation into a persistent execution loop. Instead of letting Claude stop after a partial attempt, the plugin uses Claude Code's Stop Hook behavior to keep the agent working until a clear completion promise is met.

This guide covers Ralph Wiggum Plugin install, the /ralph-wiggum:ralph-loop command, completion promises, Stop Hook behavior, Windows/WSL notes, and practical safety rules for using it without creating an expensive runaway loop.

Ralph Wiggum Plugin Quick Start

If you only need the short install path, start here:

1. Open Claude Code in the project you want to automate.
2. Make sure your current work is committed or safely backed up in Git.
3. Add the plugin marketplace with /plugin marketplace add anthropics/claude-code.
4. Install the Ralph Wiggum Plugin with /plugin install ralph-wiggum@claude-code-plugins.
5. Run /plugin and check that the ralph-wiggum namespace is available.
6. Start a loop with /ralph-wiggum:ralph-loop, a specific task, --max-iterations, and a completion promise.

The important point: installing the Ralph Wiggum Plugin is not enough. The plugin works best when you give Claude Code objective checks such as pnpm test, npm run build, pytest, ruff, or a specific command that proves the task is complete.

What Exactly Is the Ralph Wiggum Plugin?

The name comes from Ralph Wiggum in The Simpsons, but in Claude Code workflows the plugin represents a useful engineering idea: stubborn persistence. If Claude cannot get the task right the first time, the plugin pushes it to try again with the latest errors and context.

Technically, the Ralph Wiggum Plugin works through Claude Code's Stop Hook mechanism. When Claude Code tries to end a task, the plugin checks whether a predefined completion promise has appeared. If the promise is missing, the plugin blocks the stop event and sends Claude back into the task loop.

That makes it useful for tasks where "done" can be verified objectively:

• tests pass;
• build completes;
• linter errors are fixed;
• a CLI command returns success;
• a file or output contains an expected marker;
• a deployment or local verification command succeeds.

Why Use the Ralph Wiggum Plugin with Claude Code?

Without the plugin, Claude Code is often turn-based. You ask it to fix something, it attempts a patch, then you manually inspect the result and ask it to continue.

With the Ralph Wiggum Plugin, your role shifts from operator to reviewer. You define the task, set the limit, define the completion promise, and let Claude Code iterate.

Good use cases include:

1. Large refactors — moving code across many files while repeatedly running tests.
2. Test-driven development — asking Claude to keep editing until a failing test suite passes.
3. Bug fixing — reproduce, patch, run verification, and retry if the verification fails.
4. Migration work — upgrade dependencies, fix type errors, and keep building until clean.
5. Code quality cleanup — run lint, typecheck, and format commands until the output is clean.

Ralph Wiggum Plugin Install Tutorial for Claude Code

Installing the plugin is straightforward, but there are a few terminal and permission details that matter.

Step 1: Initialize Claude Code

First, make sure you can run Claude Code in the target project. If the task will modify files and run commands repeatedly, start from a clean Git state or create a temporary branch.

For fully autonomous local loops, some users start Claude Code with the permission skip flag:

claude --dangerously-skip-permissions

Use this carefully. It can be convenient for automation, but it also lets Claude run commands and edit files without repeated confirmation prompts.

Step 2: Add the Claude Code Plugin Marketplace

Inside the Claude Code terminal, add the official plugin repository:

/plugin marketplace add anthropics/claude-code

If you run into network or git clone errors, manually cloning the repository and adding a local path may be more reliable.

Step 3: Install the Ralph Wiggum Plugin

Run the plugin install command:

/plugin install ralph-wiggum@claude-code-plugins

Then verify installation:

/plugin

You should see the plugin listed, or you should see commands under the ralph-wiggum namespace.

Windows and WSL Notes

The plugin may rely on shell tools such as jq. If you use Windows, running Claude Code and the plugin inside WSL2 is usually simpler than fighting native Windows PATH and shell differences.

How to Use the Ralph Wiggum Plugin: Core Commands

The main command is:

/ralph-wiggum:ralph-loop "YOUR TASK DESCRIPTION" --max-iterations N --completion-promise "COMPLETION_TAG"

A good loop command has three parts.

1. Task Description

This is the work Claude should perform. Make it specific and verifiable.

Weak prompt:

Fix the app.

Better prompt:

Run pnpm build, inspect the errors, modify the code until pnpm build passes, and do not change unrelated files.

2. Max Iterations

--max-iterations is the safety fuse. It prevents the plugin from looping forever.

For small tasks, start with:

--max-iterations 5

For larger refactors, use 10–20 only when you have a clean Git branch and a clear verification command.

3. Completion Promise

The completion promise is the exact marker that tells the plugin the job is done.

Example:

--completion-promise "FIXED"

Then include this requirement in the task:

Only output FIXED after pnpm build and pnpm test both pass.

If Claude says "I fixed it" but does not print the exact promise, the plugin sends it back into the loop.

Real-World Example: Automating Test Fixes

Imagine npm test is failing. A practical Ralph Wiggum Plugin command could look like this:

/ralph-wiggum:ralph-loop "Run npm test, analyze the failure reasons, and modify the code in src only. Re-run tests after every fix. Keep iterating until all tests pass. Once fully passing, output FIXED." --max-iterations 15 --completion-promise "FIXED"

In this workflow:

• Ralph starts the loop.
• Claude runs the test command.
• Claude edits code based on the current failure.
• If tests still fail, the Stop Hook prevents early exit.
• The task ends only when tests pass and Claude outputs FIXED.

Example: Build-Fix Loop for a Frontend Project

For a TypeScript or Next.js project, you can use a build-focused loop:

/ralph-wiggum:ralph-loop "Run pnpm build. Fix TypeScript, lint, or import errors caused by the current branch. Avoid unrelated refactors. Re-run pnpm build after each fix. When pnpm build succeeds, output BUILD_OK." --max-iterations 10 --completion-promise "BUILD_OK"

This kind of command works better than vague prompts because Claude has a concrete success signal.

Important Safety Rules

The Ralph Wiggum Plugin is powerful, but it can create expensive or messy loops if used carelessly.

Always Use Git First

Commit or stash your current work before starting a loop. If the loop makes bad changes on iteration 8, you need an easy rollback path.

Always Set Max Iterations

Do not let an agent run without a limit. Start small, inspect the result, then increase the limit only if needed.

Use Objective Verification

The plugin works best with objective commands:

• pnpm build
• npm test
• pytest
• ruff check
• tsc --noEmit
• go test ./...

Avoid fuzzy goals like "make it better" or "improve the UI" unless you also define a review checklist.

Watch Token and API Costs

Each failed iteration can include logs, diffs, and additional reasoning. Long loops can become expensive. Use short iteration limits and narrow tasks.

FAQ

What is the Ralph Wiggum Plugin?

The Ralph Wiggum Plugin is a Claude Code plugin that keeps Claude working in a loop until a predefined completion promise is met.

How do I install the Ralph Wiggum Plugin?

Add the Claude Code plugin marketplace, then run:

/plugin install ralph-wiggum@claude-code-plugins

After installation, run /plugin to verify that the plugin or ralph-wiggum commands are available.

What command do I use after installing it?

Use:

/ralph-wiggum:ralph-loop "YOUR TASK" --max-iterations 5 --completion-promise "DONE"

Replace YOUR TASK, the iteration limit, and the completion promise with your actual verification workflow.

What is a completion promise?

A completion promise is the exact text Claude must output when the task is truly done. The plugin uses it as the stop condition.

Is the Ralph Wiggum Plugin safe?

It is safe only when you use guardrails: Git, max iterations, narrow tasks, and objective verification commands. Avoid using it on important code without a clean rollback point.

Summary

The Ralph Wiggum Plugin for Claude Code is useful when you want Claude to stop acting like a one-shot chatbot and start behaving like a persistent engineering agent. The setup is simple, but the real skill is writing a clear loop command with a specific task, a safe iteration limit, and a completion promise tied to a real verification command.

If your workflow involves repeated "run tests → fix errors → run tests again" cycles, the Ralph Wiggum Plugin can save a lot of manual babysitting—as long as you keep the loop bounded and verifiable.