Ralph Wiggum Plugin for Windows

A Windows-compatible Claude Code plugin implementing the Ralph Wiggum technique - iterative, self-referential AI development loops using PowerShell.

"Me fail English? That's unpossible!" - Ralph Wiggum

What is the Ralph Wiggum Technique?

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

while ($true) {
  Get-Content PROMPT.md | claude --continue
}

Core concept: The same prompt is fed to Claude repeatedly. Claude sees its own previous work in files and git history, allowing it to iteratively improve until the task is complete.

How It Works

1. You start a Ralph loop with a task prompt
2. Claude works on the task, modifying files
3. When Claude tries to exit, the stop hook intercepts
4. The same prompt is fed back to Claude
5. Claude sees its previous work and continues improving
6. Loop continues until completion criteria are met

Installation

Option 1: Project-Level Installation (Recommended)

Install Ralph Wiggum for a specific project only:

# Navigate to your project directory
cd C:\path\to\your\project

# Download and run installer
irm https://raw.githubusercontent.com/Arthur742Ramos/ralph-wiggum-windows/main/install.ps1 | iex

Or if you've already cloned the repository:

# Run installer from cloned repo
powershell -ExecutionPolicy Bypass -File path\to\ralph-wiggum-windows\install.ps1

The installer will automatically:

• Clone the repository (if needed)
• Create required directories in .claude/plugins/
• Copy all files to the correct locations
• Verify the installation
• Clean up temporary files

Use -KeepSource flag to keep the source repository after installation.

Option 2: Global Installation

Install globally for all projects:

# Clone directly to Claude Code plugins folder
git clone https://github.com/Arthur742Ramos/ralph-wiggum-windows ~/.claude/plugins/ralph-wiggum-windows

Option 3: Manual Installation

1. Download or clone this repository
2. Copy the entire folder to ~/.claude/plugins/ralph-wiggum-windows (global) or .claude/plugins/ralph-wiggum-windows (project-level)
3. Restart Claude Code

Verify Installation

After installation, validate the plugin and restart Claude Code:

# For project-level installation
claude plugin validate .claude/plugins/ralph-wiggum-windows

# For global installation
claude plugin validate ~/.claude/plugins/ralph-wiggum-windows

You should see these commands available in Claude Code:

• /ralph-wiggum-windows:ralph-loop - Start a Ralph loop
• /ralph-wiggum-windows:cancel-ralph - Cancel active loop
• /ralph-wiggum-windows:help - Show general help
• /ralph-wiggum-windows:help-ralph - Show detailed Ralph Wiggum technique guide

Quick Start

/ralph-wiggum-windows:ralph-loop "Build a REST API for todos with CRUD operations, validation, and tests" --completion-promise "API COMPLETE" --max-iterations 30

Commands

/ralph-wiggum-windows:ralph-loop

Start a Ralph loop in your current session.

Usage:

/ralph-wiggum-windows:ralph-loop "<prompt>" [--max-iterations N] [--completion-promise "<text>"]

Options:

Option	Description	Default
--max-iterations <n>	Maximum iterations before auto-stop	unlimited
--completion-promise <text>	Phrase that signals successful completion	none

Examples:

# Run until "DONE" is achieved, max 50 iterations
/ralph-wiggum-windows:ralph-loop "Refactor the cache layer for better performance" --completion-promise "DONE" --max-iterations 50

# Run for exactly 10 iterations
/ralph-wiggum-windows:ralph-loop "Explore optimization opportunities" --max-iterations 10

# Run indefinitely (use with caution!)
/ralph-wiggum-windows:ralph-loop "Continuously improve test coverage"

/ralph-wiggum-windows:cancel-ralph

Cancel an active Ralph loop immediately.

/ralph-wiggum-windows:cancel-ralph

/ralph-wiggum-windows:help

Display comprehensive help about the Ralph Wiggum technique and all available commands.

/ralph-wiggum-windows:help

Completion Promises

To signal that a task is complete, Claude must output a <promise> tag:

<promise>TASK COMPLETE</promise>

Important rules:

• The promise text must match exactly what you specified in --completion-promise
• Claude should only output the promise when the statement is genuinely true
• The stop hook specifically looks for <promise>...</promise> tags

Monitoring Your Loop

While a Ralph loop is running, you can check its status:

# View current iteration
Select-String '^iteration:' .claude/ralph-loop.local.md

# View full state
Get-Content .claude/ralph-loop.local.md -Head 10

When to Use Ralph

Good Use Cases

• Well-defined tasks with clear success criteria
• Iterative development requiring refinement cycles
• Greenfield projects where Claude can build incrementally
• Refactoring tasks with measurable outcomes
• Test coverage improvements

Not Recommended For

• Tasks requiring human judgment or design decisions
• One-shot operations (just use Claude normally)
• Tasks with unclear or subjective success criteria
• Debugging production issues (need human oversight)
• Tasks where you need to provide frequent feedback

Windows Compatibility

This fork was created specifically for Windows users. The original Ralph Wiggum plugin uses bash/jq which don't work natively on Windows.

Changes from the original:

Original (Unix)	This Fork (Windows)
stop-hook.sh	stop-hook.ps1
jq for JSON parsing	ConvertFrom-Json
bash scripts	PowerShell scripts
Unix path conventions	Windows path conventions

File Structure

ralph-wiggum-windows/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── commands/
│   ├── cancel-ralph.md      # /cancel-ralph command
│   ├── help.md              # /help command
│   ├── help-ralph.md        # /help-ralph command (detailed guide)
│   └── ralph-loop.md        # /ralph-loop command
├── hooks/
│   └── stop-hook.ps1        # Stop hook (PowerShell)
├── scripts/
│   └── setup-ralph-loop.ps1 # Setup script (PowerShell)
├── install.ps1              # Automatic installer script
├── LICENSE
├── CONTRIBUTING.md
└── README.md

Debugging

Debug logs are automatically written to .claude/ralph-debug.log in your project directory whenever the stop hook runs. This file contains:

• Timestamps for each hook trigger
• Parsed state file values (iteration, max iterations, completion promise)
• Transcript parsing results
• Success/failure status for each iteration

To view debug logs:

Get-Content .claude/ralph-debug.log

Troubleshooting

Plugin not recognized / Commands not showing

• Run claude plugin validate ~/.claude/plugins/ralph-wiggum-windows to check for errors
• If validation fails, check that plugin.json has the correct format (especially repository should be a string URL, not an object)
• Restart Claude Code after fixing any issues

Loop not starting

• Verify the plugin is installed in ~/.claude/plugins/ralph-wiggum-windows
• Check that plugin.json exists in .claude-plugin/
• Restart Claude Code

Loop not stopping

• Use /ralph-wiggum-windows:cancel-ralph to force stop
• Manually delete .claude/ralph-loop.local.md in your project directory

PowerShell execution policy errors

Run PowerShell as Administrator and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Credits

• Original technique: Geoffrey Huntley
• Original plugin: Anthropic Claude Code team
• Windows fork: CloudBuild Team

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Links

• Ralph Wiggum Technique (ghuntley.com)
• Original Ralph Wiggum Plugin
• Claude Code Documentation
• Windows compatibility issue #14817