Ralph wiggum Claude Code plugin: the wiring, and the two things that break it

On this page#

• What the integration actually does
• The wiring
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

The ralph wiggum Claude Code plugin turns one Claude Code task into a bounded retry loop. It does not create a second agent, add memory, or guarantee correctness. It uses Claude Code’s extension points to keep the current task running until Claude emits an explicit completion promise or reaches an iteration limit.

That distinction matters. People often describe Ralph as “letting Claude work autonomously until the feature is finished.” The mechanism is narrower:

| What people assume | What actually happens | |---|---| | Ralph manages a team of agents | One Claude Code task is repeatedly continued | | It knows when the implementation is correct | It watches for a completion-promise string | | It remembers every decision forever | It operates within Claude Code’s available context | | It can bypass permissions | Normal tool and permission boundaries still apply | | It replaces tests and review | Tests and invariants must define completion |

Claude Code is Anthropic’s agentic coding environment: it can inspect a repository, edit files, run permitted commands, and use project instructions. The official overview explains that operating model; Ralph changes the stopping behavior, not the underlying capabilities (Claude Code overview).

That makes Ralph useful for tasks with a mechanical convergence path: implement, run checks, inspect failures, repair, and repeat. It is a bad fit for ambiguous product decisions, migrations without rollback plans, or repositories whose tests do not express the real invariants.

The hard truth is that Ralph does not make a weak task specification stronger. It merely gives that specification more opportunities to damage the repository.

Photo by cottonbro studio on Pexels.

The wiring#

The clean setup has four parts: install the official plugin, put repository invariants in CLAUDE.md, define a narrow task prompt, and start the loop with both a completion promise and a hard iteration limit. Do not wrap claude in an external infinite shell loop; that creates the wrong process model.

Install the plugin inside Claude Code#

Open Claude Code in the target repository and use its plugin interface:

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

Then confirm that the Ralph command is available:

/help

The command list should include /ralph-loop. If it does not, stop there. Restarting work with an unverified installation only makes later failures harder to diagnose.

Plugins extend Claude Code through supported configuration and lifecycle mechanisms. Keep the installation path aligned with the current Claude Code documentation, because commands copied from an old post can describe a different plugin interface.

Put non-negotiable rules in CLAUDE.md#

The loop prompt describes one task. CLAUDE.md describes the repository contract that must survive every iteration.

# Repository operating rules

- Preserve public API behavior unless the task explicitly changes it.
- Do not disable, skip, or delete failing tests.
- Do not replace assertions with weaker assertions.
- Keep changes inside the requested package.
- Run the repository's required checks before declaring completion.
- If a required check cannot run, report the blocker and do not emit the completion promise.

Replace the generic boundaries with real ones: permitted directories, required commands, generated-file rules, and architectural constraints. Do not bury these in a giant Ralph prompt. Repository-wide rules belong in repository-level instructions.

Claude Code’s documentation is the authority for how project instructions and settings are loaded (official documentation). Ralph consumes that environment; it does not create a parallel configuration system.

Write a convergence prompt#

A good Ralph prompt contains an observable end state, permitted scope, required checks, and a rule for emitting the completion promise.

Implement the requested change in <target-area>.

Required behavior:
- <observable behavior>
- <invariant that must remain true>

Scope:
- You may edit <allowed paths>.
- Do not change <excluded paths or interfaces>.

Verification:
- Run <required check command>.
- Inspect the resulting diff for unrelated changes.
- Do not weaken or remove tests to make the check pass.

When every requirement is satisfied and verification passes, output:
RALPH_COMPLETE

“Fix the module” is not a convergence prompt. It gives the loop no stable target and invites speculative edits.

If your repository lacks explicit operating rules, the PairFoundry Agent Operating Kit is the relevant next layer: the value is not a clever loop, but a durable contract for how an agent may change production code.

Start a bounded loop#

Invoke Ralph from the existing Claude Code session:

/ralph-loop "<task prompt>" --completion-promise "RALPH_COMPLETE" --max-iterations <your-limit>

Replace <task prompt> and <your-limit> deliberately. The limit is a circuit breaker, not a productivity setting. It should be low enough that a wrong assumption cannot produce an unlimited sequence of edits.

The completion promise must be unique and must appear only after verification. Do not use ordinary prose such as done, finished, or looks good; those phrases can occur in explanations before the repository is actually ready.

The two things that break it#

Two failures account for most broken Ralph setups: launching nested Claude Code processes and using a completion promise that can fire before the checks pass. The first breaks execution immediately. The second is worse because the loop appears successful while returning unfinished work.

Failure: nested Claude Code sessions#

The concrete symptom is a nested-session error when a shell wrapper repeatedly launches claude from inside an active Claude Code session. The wiring is wrong: Ralph should continue the current task through the plugin’s lifecycle hook, not spawn another interactive Claude process.

Wrong:

while true; do
  claude "<task>"
done

Right:

/ralph-loop "<task>" --completion-promise "RALPH_COMPLETE" --max-iterations <your-limit>

Remove aliases, task runners, or wrapper scripts that secretly invoke claude again. Start one Claude Code session at the repository root, then run /ralph-loop inside it. The official Claude Code overview explains the agent session being extended; Ralph is not an external supervisor for recursively launching that session.

Failure: the completion promise fires early#

The concrete symptom is: the loop stops, Claude prints the configured promise, but required checks are failing or were never run. This is not a plugin crash. It is a false-positive termination caused by treating model output as proof.

Bad instruction:

When you think the change is done, say DONE.

Better instruction:

Run <required checks>.
Confirm they pass.
Inspect the diff for unrelated changes.
Only then output RALPH_COMPLETE on its own line.
If verification cannot run, do not output that string.

Also keep the literal promise out of examples, planning text, and copied issue content. If the task prompt repeatedly discusses the exact sentinel, Claude can reproduce it while explaining what remains.

The fix is structural: make tests authoritative, make the promise conditional on those tests, and independently verify the final state.

Photo by Al Nahian on Pexels.

Verifying it works#

A working Ralph setup must prove continuation, termination, and repository correctness separately. Seeing repeated assistant output proves only that something looped. It does not prove that the hook used the intended condition or that the final change preserved your invariants.

Use a disposable, tightly scoped task:

Make the smallest permitted change in <safe target>.
Run <required check>.
Do not emit RALPH_COMPLETE until the check passes.

Then verify:

• Claude performs more than one work cycle when the first check fails.
• The loop stops when the exact completion promise is emitted.
• The loop stops at the configured limit when the promise is withheld.
• Required checks pass outside the agent’s narrative.
• The final diff contains no skipped tests, weakened assertions, or unrelated cleanup.
• git status contains only expected files.

The external check is essential. Claude saying “tests pass” is a report; the command result is evidence.

For a broader treatment of connecting instructions, hooks, checks, and repository boundaries, use the Wiring It In hub. If the instruction hierarchy itself is unfamiliar, start with the free PairFoundry foundations track.

Team considerations#

A second developer will inherit every hidden assumption in the loop: installation state, permission settings, repository instructions, completion semantics, and expected checks. If those assumptions live only in one engineer’s terminal history, the integration is not team-ready.

Commit the repository contract, but do not commit personal permission grants or machine-specific paths. Document:

• Which plugin must be installed.
• The canonical Ralph prompt or prompt template.
• The permitted edit scope.
• The required verification commands.
• The completion-promise convention.
• The iteration-limit policy.
• The rollback procedure.
• Which tasks are explicitly excluded.

Keep the prompt near the code or workflow it governs. A pasted chat message will drift; a reviewed repository artifact can change with the system.

Permission differences are another predictable trap. One developer may have previously approved a command that blocks for everyone else. Ralph cannot negotiate unattended prompts safely, so the team must agree on the commands the loop may execute and retain a human checkpoint for destructive operations.

Do not standardize Ralph before standardizing tests and invariants. The loop amplifies whatever governance already exists. Teams still defining their operating model can compare the available PairFoundry packs before choosing how much structure to adopt.

Photo by Jakub Zerdzicki on Pexels.

Related reading#

• Claude Code Docker, including the failure mode nobody documents
• Claude Code JetBrains: what to check before you trust the connection

FAQ#

When should I not use Ralph on a production repository?#

Do not use it when success requires subjective judgment, destructive data operations, undocumented credentials, or coordination outside the repository. It is also the wrong tool when the test suite does not represent the behavior you must preserve.

How is this different from ordinary Claude Code usage?#

Ordinary usage stops when Claude finishes its response or returns control. Ralph adds a bounded continuation mechanism tied to a completion promise. It does not replace Claude Code’s tools, project instructions, permissions, or context model.

What should the team commit to the repository?#

Commit shared instructions, prompt templates, verification commands, and task boundaries. Keep personal approvals, credentials, absolute machine paths, and developer-specific settings out of version control. Follow the configuration model described in the official Claude Code documentation.

How do I back out after a bad loop?#

Stop the loop, inspect the complete diff, and revert only the Ralph-generated changes using your team’s normal version-control workflow. Do not blindly discard the working tree: unrelated developer changes may be present. Recovery begins with identifying the exact files and commits the loop touched.

Can the completion promise replace CI?#

No. The promise is model-generated text, not independent verification. CI, repository checks, and human review remain the acceptance boundary. Ralph may drive work toward that boundary; it cannot certify that the boundary was met.