surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / ralph-wiggum / README.md

179 lines · 5.1 KBPreview CodeRaw

1	# Ralph Wiggum Plugin
2
3	Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Claude Code.
4
5	## What is Ralph?
6
7	Ralph 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
9	The technique is named after Ralph Wiggum from The Simpsons, embodying the philosophy of persistent iteration despite setbacks.
10
11	### Core Concept
12
13	This 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
27	The 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
29	This 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
41	Claude 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
52	Start 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
65	Cancel 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
80	Build a REST API for todos.
81
82	When 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
96	Phase 1: User authentication (JWT, tests)
97	Phase 2: Product catalog (list/search, tests)
98	Phase 3: Shopping cart (add/remove, tests)
99
100	Output <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
109	Implement feature X following TDD:
110	1. Write failing tests
111	2. Implement feature
112	3. Run tests
113	4. If any fail, debug and fix
114	5. Refactor if needed
115	6. Repeat until all green
116	7. Output: <promise>COMPLETE</promise>
117	```
118
119	### 4. Escape Hatches
120
121	Always 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
138	Ralph embodies several key principles:
139
140	### 1. Iteration > Perfection
141	Don'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
147	Success depends on writing good prompts, not just having a good model.
148
149	### 4. Persistence Wins
150	Keep 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
179	Run `/help` in Claude Code for detailed command reference and examples.