wiggum.sh

The Ralph Wiggum technique for Claude Code. Iterative AI development loops with completion promises.

curl -fsSL wiggum.sh | bash Copied!

What it is

A Claude Code plugin that runs your prompt in a loop. Same prompt, every iteration. Claude sees its previous work in modified files and git history, not by re-reading a growing conversation. Each iteration gets a fresh agent with a clean context window.

The loop stops when Claude outputs a completion promise you define, or when it hits a max iteration count. Without either, it runs forever.

Why fresh agents

Same-session loops context bloat

A stop hook intercepts exit and re-feeds the prompt in the same session. Every iteration adds to the context window. By iteration 20, Claude is re-reading the full history of attempts, tool calls, and dead ends. Context fills up. Quality degrades.

wiggum.sh fresh context

Each iteration spawns a new Claude Code agent. Context starts clean. Claude reads the prompt, looks at the filesystem, and picks up where the last agent left off. Iteration 50 gets the same quality context window as iteration 1.

Usage

# Install (restart Claude Code after)
curl -fsSL wiggum.sh | bash

# Inline prompt
/ralph-loop Build a REST API --completion-promise 'DONE' --max-iterations 50

# Prompt from file (for large, multi-page goals)
/ralph-loop --prompt-file PROMPT.md --completion-promise 'COMPLETE' --max-iterations 100

# Cancel a running loop
/cancel-ralph
FlagDescription
--prompt-file <path>Read prompt from a file instead of inline. The file contents become the loop prompt.
--max-iterations <n>Stop after N iterations. Default: unlimited (runs forever).
--completion-promise <text>Phrase that signals completion. Claude outputs <promise>TEXT</promise> when genuinely true.

How it works

  1. /ralph-loop creates a state file at .claude/ralph-loop.local.md
  2. A stop hook intercepts Claude's exit attempts
  3. The same prompt is re-fed with an incremented iteration counter
  4. Claude sees its previous work in modified files and git history
  5. Loop exits when the completion promise is detected or max iterations reached

Completion promises

To signal completion, Claude outputs a <promise> tag with your phrase. The stop hook checks for an exact match. Claude can only output the promise when the statement is genuinely true. It cannot lie to escape the loop.

On the final iteration, Claude includes a handoff brief: 3-6 bullets pointing to where a human can dig in and verify the work.

# Example: Claude outputs this when tests actually pass
<promise>ALL TESTS PASSING</promise>