Ralph Wiggum Plugin

1# Ralph Wiggum Plugin
2 
3Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Claude Code.
4 
5## What is Ralph?
6 
7Ralph 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.
8 
9The technique is named after Ralph Wiggum from The Simpsons, embodying the philosophy of persistent iteration despite setbacks.
10 
11### Core Concept
12 
13This plugin implements Ralph using a **Stop hook** that intercepts Claude's exit attempts:
14 
15```bash
16# You run ONCE:
17/ralph-loop "Your task description" --completion-promise "DONE"
18 
19# Then Claude Code automatically:
20# 1. Works on the task
21# 2. Tries to exit
22# 3. Stop hook blocks exit
23# 4. Stop hook feeds the SAME prompt back
24# 5. Repeat until completion
25```
26 
27The loop happens **inside your current session** - you don't need external bash loops. The Stop hook in `hooks/stop-hook.sh` creates the self-referential feedback loop by blocking normal session exit.
28 
29This creates a **self-referential feedback loop** where:
30- The prompt never changes between iterations
31- Claude's previous work persists in files
32- Each iteration sees modified files and git history
33- Claude autonomously improves by reading its own past work in files
34 
35## Quick Start
36 
37```bash
38/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50
39```
40 
41Claude will:
42- Implement the API iteratively
43- Run tests and see failures
44- Fix bugs based on test output
45- Iterate until all requirements met
46- Output the completion promise when done
47 
48## Commands
49 
50### /ralph-loop
51 
52Start a Ralph loop in your current session.
53 
54**Usage:**
55```bash
56/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"
57```
58 
59**Options:**
60- `--max-iterations <n>` - Stop after N iterations (default: unlimited)
61- `--completion-promise <text>` - Phrase that signals completion
62 
63### /cancel-ralph
64 
65Cancel the active Ralph loop.
66 
67**Usage:**
68```bash
69/cancel-ralph
70```
71 
72## Prompt Writing Best Practices
73 
74### 1. Clear Completion Criteria
75 
76❌ Bad: "Build a todo API and make it good."
77 
78✅ Good:
79```markdown
80Build a REST API for todos.
81 
82When complete:
83- All CRUD endpoints working
84- Input validation in place
85- Tests passing (coverage > 80%)
86- README with API docs
87- Output: <promise>COMPLETE</promise>
88```
89 
90### 2. Incremental Goals
91 
92❌ Bad: "Create a complete e-commerce platform."
93 
94✅ Good:
95```markdown
96Phase 1: User authentication (JWT, tests)
97Phase 2: Product catalog (list/search, tests)
98Phase 3: Shopping cart (add/remove, tests)
99 
100Output <promise>COMPLETE</promise> when all phases done.
101```
102 
103### 3. Self-Correction
104 
105❌ Bad: "Write code for feature X."
106 
107✅ Good:
108```markdown
109Implement feature X following TDD:
1101. Write failing tests
1112. Implement feature
1123. Run tests
1134. If any fail, debug and fix
1145. Refactor if needed
1156. Repeat until all green
1167. Output: <promise>COMPLETE</promise>
117```
118 
119### 4. Escape Hatches
120 
121Always use `--max-iterations` as a safety net to prevent infinite loops on impossible tasks:
122 
123```bash
124# Recommended: Always set a reasonable iteration limit
125/ralph-loop "Try to implement feature X" --max-iterations 20
126 
127# In your prompt, include what to do if stuck:
128# "After 15 iterations, if not complete:
129#  - Document what's blocking progress
130#  - List what was attempted
131#  - Suggest alternative approaches"
132```
133 
134**Note**: The `--completion-promise` uses exact string matching, so you cannot use it for multiple completion conditions (like "SUCCESS" vs "BLOCKED"). Always rely on `--max-iterations` as your primary safety mechanism.
135 
136## Philosophy
137 
138Ralph embodies several key principles:
139 
140### 1. Iteration > Perfection
141Don't aim for perfect on first try. Let the loop refine the work.
142 
143### 2. Failures Are Data
144"Deterministically bad" means failures are predictable and informative. Use them to tune prompts.
145 
146### 3. Operator Skill Matters
147Success depends on writing good prompts, not just having a good model.
148 
149### 4. Persistence Wins
150Keep trying until success. The loop handles retry logic automatically.
151 
152## When to Use Ralph
153 
154**Good for:**
155- Well-defined tasks with clear success criteria
156- Tasks requiring iteration and refinement (e.g., getting tests to pass)
157- Greenfield projects where you can walk away
158- Tasks with automatic verification (tests, linters)
159 
160**Not good for:**
161- Tasks requiring human judgment or design decisions
162- One-shot operations
163- Tasks with unclear success criteria
164- Production debugging (use targeted debugging instead)
165 
166## Real-World Results
167 
168- Successfully generated 6 repositories overnight in Y Combinator hackathon testing
169- One $50k contract completed for $297 in API costs
170- Created entire programming language ("cursed") over 3 months using this approach
171 
172## Learn More
173 
174- Original technique: https://ghuntley.com/ralph/
175- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
176 
177## For Help
178 
179Run `/help` in Claude Code for detailed command reference and examples.
180