tuannvm avatar

ralph-wiggum

Install

/plugin install ralph-wiggum@plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add tuannvm/plugins.

Contents

Discovered from source

Commands 3

Cancel Ralph

Check if a Ralph loop is active:

if [[ -f .claude/ralph-loop.local.md ]]; then
  grep '^iteration:' .claude/ralph-loop.local.md | sed 's/iteration: *//'
else
  echo "No active Ralph loop found."
fi

If an iteration number was shown (not "No active..."), cancel the loop:

rm .claude/ralph-loop.local.md

Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration number from the first command.

If no active loop was found, say so.

Ralph Wiggum Plugin Help

Please explain the following to the user:

What is the Ralph Wiggum Technique?

The Ralph Wiggum technique is an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.

Core concept:

while :; do
  cat PROMPT.md | claude-code --continue
done

The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.

Each iteration:

  1. Claude receives the SAME prompt
  2. Works on the task, modifying files
  3. Tries to exit
  4. Stop hook intercepts and feeds the same prompt again
  5. Claude sees its previous work in the files
  6. Iteratively improves until completion

The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.

Available Commands

/ralph-loop "" [OPTIONS]

Start a Ralph loop in your current session.

IMPORTANT: PROMPT must always be wrapped in quotes.

Usage:

/ralph-loop "Refactor the cache layer" --max-iterations 20
/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"

Options:

  • "PROMPT" - The task prompt (REQUIRED, must be quoted)
  • --max-iterations <n> - Max iterations before auto-stop (REQUIRED if no completion-promise)
  • --completion-promise "<text>" - Promise phrase to signal completion (REQUIRED if no max-iterations, must be quoted)

Requirements:

  • PROMPT must always be wrapped in quotes
  • At least one exit condition MUST be specified to prevent infinite loops

How it works:

  1. Creates .claude/ralph-loop.local.md state file
  2. You work on the task
  3. When you try to exit, stop hook intercepts
  4. Same prompt fed back
  5. You see your previous work
  6. Continues until promise detected or max iterations

/cancel-ralph

Cancel an active Ralph loop (removes the loop state file).

Usage:

/cancel-ralph

How it works:

  • Checks for active loop state file
  • Removes .claude/ralph-loop.local.md
  • Reports cancellation with iteration count

Key Concepts

Completion Promises

To signal completion, Claude must output a <promise> tag:

<promise>TASK COMPLETE</promise>

The stop hook looks for this specific tag. At least one exit condition (max-iterations or completion-promise) is required.

Self-Reference Mechanism

The "loop" doesn't mean Claude talks to itself. It means:

  • Same prompt repeated
  • Claude's work persists in files
  • Each iteration sees previous attempts
  • Builds incrementally toward goal

Example

Interactive Bug Fix

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

You'll see Ralph:

  • Attempt fixes
  • Run tests
  • See failures
  • Iterate on solution
  • In your current session

When to Use Ralph

Good for:

  • Well-defined tasks with clear success criteria
  • Tasks requiring iteration and refinement
  • Iterative development with self-correction
  • Greenfield projects

Not good for:

  • Tasks requiring human judgment or design decisions
  • One-shot operations
  • Tasks with unclear success criteria
  • Debugging production issues (use targeted debugging instead)

Learn More

Ralph Loop Command

Run this command to initialize the Ralph loop:

"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS

Execute the above command using Bash, then work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.

CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

Hooks 1

Sponsors

Details

Marketplace
tuannvm/plugins
Source
plugins/ralph-wiggum
Category
Community

More from tuannvm/plugins

All 4