ralph-wiggum

Ralph Wiggum - Windows Edition

A Windows-compatible port of the official Ralph Wiggum plugin for Claude Code

Why This Exists

The official Ralph Wiggum plugin from Anthropic uses Bash scripts which don't work natively on Windows. This port replaces all Bash scripts with PowerShell equivalents, making the plugin fully functional on Windows systems.

What is Ralph Wiggum?

Ralph Wiggum is a self-referential development loop plugin for Claude Code. It creates an iterative feedback loop where:

1. You give Claude a task with a completion condition
2. Claude works on the task and attempts to exit
3. The stop hook intercepts the exit and feeds the same prompt back
4. Claude sees its previous work in files and continues iterating
5. The loop continues until the task is truly complete (or max iterations reached)

This is incredibly powerful for complex development tasks where multiple iterations of refinement are needed.

Installation

Option 1: Install via Claude Code CLI (Recommended)

claude plugins:add byigitt/ralph-wiggum-windows

Option 2: Manual Installation

1. Clone this repository:

   git clone https://github.com/byigitt/ralph-wiggum-windows.git
   

2. Copy the plugin to your Claude plugins directory:

   # Create plugins directory if it doesn't exist
   New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\plugins" -Force
   
   # Copy the plugin
   Copy-Item -Path "ralph-wiggum-windows\plugins\ralph-wiggum" -Destination "$env:USERPROFILE\.claude\plugins\ralph-wiggum" -Recurse
   

3. Restart Claude Code - the plugin will be automatically detected.

Verify Installation

Run this command in Claude Code to verify the plugin is installed:

/ralph-wiggum:help

Usage

Starting a Loop

/ralph-wiggum:ralph-loop [your task] [options]

Options:

Option	Description
--max-iterations <n>	Maximum iterations before auto-stop (default: unlimited)
--completion-promise '<text>'	Text that signals task completion
-h, --help	Show help message

Examples

Build a feature with test verification:

/ralph-wiggum:ralph-loop Build a REST API for user management --completion-promise "ALL TESTS PASS" --max-iterations 30

Fix a bug with iteration limit:

/ralph-wiggum:ralph-loop Fix the authentication timeout bug --max-iterations 10

Open-ended refactoring:

/ralph-wiggum:ralph-loop Refactor the database layer to use repository pattern

Cancelling a Loop

Force-stop an active loop:

/ralph-wiggum:cancel-ralph

Monitoring Progress

Check current iteration:

Get-Content .claude/ralph-loop.local.md | Select-String "iteration:"

View full state:

Get-Content .claude/ralph-loop.local.md

How Completion Works

To signal that a task is complete, Claude must output:

<promise>YOUR_COMPLETION_TEXT</promise>

Important: The completion promise must be genuinely true. Claude is instructed not to lie just to escape the loop - the statement must be verifiable.

Good completion promises:

• "ALL TESTS PASS" - Verifiable by running tests
• "LINTER CLEAN" - Verifiable by running linter
• "BUILD SUCCEEDS" - Verifiable by running build
• "FEATURE COMPLETE" - Subjective but clear

Commands Reference

Command	Description
/ralph-wiggum:ralph-loop	Start a new self-referential loop
/ralph-wiggum:cancel-ralph	Cancel an active loop
/ralph-wiggum:help	Show plugin documentation

Best Practices

1. Set Clear Completion Criteria - Define what "done" means precisely with --completion-promise
2. Use Safety Limits - Always set --max-iterations as a safety net for complex tasks
3. Make Promises Verifiable - Use completion promises that can be objectively verified (tests pass, build succeeds, etc.)
4. Break Down Large Tasks - For very large tasks, break them into smaller loops
5. Monitor Progress - Check the iteration count periodically to ensure the loop is making progress

Requirements

• Windows 10/11
• PowerShell 5.1+ (included with Windows)
• Claude Code CLI

Project Structure