Ralph Loop Plugin

Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Claude Code.

What is Ralph Loop?

Ralph Loop is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: "Ralph is a Bash loop" - a simple while true that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.

Core Concept

This plugin implements Ralph using a Stop hook that intercepts Claude's exit attempts:

# You run ONCE:
/ralph-loop "Your task description" --completion-promise "DONE"

# Then Claude Code automatically:
# 1. Works on the task
# 2. Tries to exit
# 3. Stop hook blocks exit
# 4. Stop hook feeds the SAME prompt back
# 5. Repeat until completion

The loop happens inside your current session - you don't need external bash loops.

Installation

From Local Path

# Clone this repo
git clone https://github.com/mgluck/ralph-loop-plugin.git

# Install in Claude Code
claude plugins install /path/to/ralph-loop-plugin

Manual Installation

Copy the plugin files to your Claude Code plugins directory:

mkdir -p ~/.claude/plugins/marketplaces/local-plugins/plugins/ralph-loop
cp -r * ~/.claude/plugins/marketplaces/local-plugins/plugins/ralph-loop/

Then run /refresh in Claude Code.

Quick Start

/ralph-loop "Build a REST API for todos. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 20

Claude will iterate until:

• It outputs <promise>COMPLETE</promise> (task done)
• Or reaches 20 iterations (safety limit)

Commands

/ralph-loop

Start a Ralph loop in your current session.

Usage:

/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"

Options:

• --max-iterations <n> - Stop after N iterations (default: unlimited)
• --completion-promise <text> - Phrase that signals completion

/cancel-ralph

Cancel the active Ralph loop.

/cancel-ralph

/help

Show help and examples.

Prompt Writing Tips

Clear Completion Criteria

Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Tests passing
- Output: <promise>COMPLETE</promise>

Always Use Safety Limits

# Always set --max-iterations to prevent infinite loops
/ralph-loop "Implement feature X" --max-iterations 20

How It Works

1. /ralph-loop creates a state file at .claude/ralph-loop.local.md
2. When Claude tries to exit, the Stop hook reads the state
3. If completion promise not detected, hook blocks exit and feeds the same prompt back
4. Claude sees its previous work in files and continues
5. Loop ends when promise is detected or max iterations reached

Files

ralph-loop-plugin/
├── .claude-plugin/
│   └── plugin.json       # Plugin metadata
├── commands/
│   ├── ralph-loop.md     # Start loop command
│   ├── cancel-ralph.md   # Cancel loop command
│   └── help.md           # Help command
├── hooks/
│   ├── hooks.json        # Hook definitions
│   ├── stop-hook.sh      # Main loop logic
│   └── post-tool-reminder.sh
├── scripts/
│   └── setup-ralph-loop.sh
└── README.md

Requirements

• Claude Code v2.1.0+
• jq installed (for JSON parsing)
• perl installed (for regex in promise detection)
• Bash 4.0+

Learn More

• Original technique: https://ghuntley.com/ralph/
• Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

License

MIT