Skip to content

Commit c672553

Browse files
jonathanpeterwujonathanpeterwu
committed
feat(plugins): add Ralph Wiggum Claude Code plugin
Adds the official Ralph Wiggum plugin from anthropics/claude-code for iterative self-referential AI development loops. Commands: - /ralph-loop - Start a loop with completion promise and max iterations - /cancel-ralph - Cancel active loop - /help - Plugin documentation The Stop hook intercepts session exit and feeds the same prompt back, enabling iterative refinement until task completion.
1 parent df1e5fd commit c672553

8 files changed

Lines changed: 728 additions & 0 deletions

File tree

‎plugins/ralph-wiggum/.claude-plugin/plugin.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"name": "ralph-wiggum",
3+
"version": "1.0.0",
4+
"description": "Implementation of the Ralph Wiggum technique - continuous self-referential AI loops for interactive iterative development. Run Claude in a while-true loop with the same prompt until task completion.",
5+
"author": {
6+
"name": "Anthropic / StackMemory",
7+
"url": "https://github.com/stackmemoryai/stackmemory"
8+
}
9+
}

‎plugins/ralph-wiggum/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
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+
## Installation
30+
31+
### Option 1: Via StackMemory
32+
33+
```bash
34+
# If using StackMemory
35+
stackmemory setup-mcp # Includes Ralph plugin registration
36+
```
37+
38+
### Option 2: Manual Installation
39+
40+
Copy this plugin directory to your Claude Code plugins location:
41+
42+
```bash
43+
cp -r plugins/ralph-wiggum ~/.claude/plugins/
44+
```
45+
46+
Or symlink it:
47+
48+
```bash
49+
ln -s "$(pwd)/plugins/ralph-wiggum" ~/.claude/plugins/ralph-wiggum
50+
```
51+
52+
## Quick Start
53+
54+
```bash
55+
/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
56+
```
57+
58+
Claude will:
59+
- Implement the API iteratively
60+
- Run tests and see failures
61+
- Fix bugs based on test output
62+
- Iterate until all requirements met
63+
- Output the completion promise when done
64+
65+
## Commands
66+
67+
### /ralph-loop
68+
69+
Start a Ralph loop in your current session.
70+
71+
**Usage:**
72+
```bash
73+
/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"
74+
```
75+
76+
**Options:**
77+
- `--max-iterations <n>` - Stop after N iterations (default: unlimited)
78+
- `--completion-promise <text>` - Phrase that signals completion
79+
80+
### /cancel-ralph
81+
82+
Cancel the active Ralph loop.
83+
84+
**Usage:**
85+
```bash
86+
/cancel-ralph
87+
```
88+
89+
## Prompt Writing Best Practices
90+
91+
### 1. Clear Completion Criteria
92+
93+
Bad: "Build a todo API and make it good."
94+
95+
Good:
96+
```markdown
97+
Build a REST API for todos.
98+
99+
When complete:
100+
- All CRUD endpoints working
101+
- Input validation in place
102+
- Tests passing (coverage > 80%)
103+
- README with API docs
104+
- Output: <promise>COMPLETE</promise>
105+
```
106+
107+
### 2. Incremental Goals
108+
109+
Bad: "Create a complete e-commerce platform."
110+
111+
Good:
112+
```markdown
113+
Phase 1: User authentication (JWT, tests)
114+
Phase 2: Product catalog (list/search, tests)
115+
Phase 3: Shopping cart (add/remove, tests)
116+
117+
Output <promise>COMPLETE</promise> when all phases done.
118+
```
119+
120+
### 3. Self-Correction
121+
122+
Bad: "Write code for feature X."
123+
124+
Good:
125+
```markdown
126+
Implement feature X following TDD:
127+
1. Write failing tests
128+
2. Implement feature
129+
3. Run tests
130+
4. If any fail, debug and fix
131+
5. Refactor if needed
132+
6. Repeat until all green
133+
7. Output: <promise>COMPLETE</promise>
134+
```
135+
136+
### 4. Escape Hatches
137+
138+
Always use `--max-iterations` as a safety net:
139+
140+
```bash
141+
# Recommended: Always set a reasonable iteration limit
142+
/ralph-loop "Try to implement feature X" --max-iterations 20
143+
```
144+
145+
## When to Use Ralph
146+
147+
**Good for:**
148+
- Well-defined tasks with clear success criteria
149+
- Tasks requiring iteration and refinement (e.g., getting tests to pass)
150+
- Greenfield projects where you can walk away
151+
- Tasks with automatic verification (tests, linters)
152+
153+
**Not good for:**
154+
- Tasks requiring human judgment or design decisions
155+
- One-shot operations
156+
- Tasks with unclear success criteria
157+
- Production debugging (use targeted debugging instead)
158+
159+
## Learn More
160+
161+
- Original technique: https://ghuntley.com/ralph/
162+
- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
163+
- Official Claude Code plugin: https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum

‎plugins/ralph-wiggum/commands/cancel-ralph.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: "Cancel active Ralph Wiggum loop"
3+
allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
4+
hide-from-slash-command-tool: "true"
5+
---
6+
7+
# Cancel Ralph
8+
9+
To cancel the Ralph loop:
10+
11+
1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
12+
13+
2. **If NOT_FOUND**: Say "No active Ralph loop found."
14+
15+
3. **If EXISTS**:
16+
- Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
17+
- Remove the file using Bash: `rm .claude/ralph-loop.local.md`
18+
- Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

‎plugins/ralph-wiggum/commands/help.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
description: "Explain Ralph Wiggum technique and available commands"
3+
---
4+
5+
# Ralph Wiggum Plugin Help
6+
7+
Please explain the following to the user:
8+
9+
## What is the Ralph Wiggum Technique?
10+
11+
The Ralph Wiggum technique is an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
12+
13+
**Core concept:**
14+
```bash
15+
while :; do
16+
cat PROMPT.md | claude-code --continue
17+
done
18+
```
19+
20+
The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
21+
22+
**Each iteration:**
23+
1. Claude receives the SAME prompt
24+
2. Works on the task, modifying files
25+
3. Tries to exit
26+
4. Stop hook intercepts and feeds the same prompt again
27+
5. Claude sees its previous work in the files
28+
6. Iteratively improves until completion
29+
30+
The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.
31+
32+
## Available Commands
33+
34+
### /ralph-loop <PROMPT> [OPTIONS]
35+
36+
Start a Ralph loop in your current session.
37+
38+
**Usage:**
39+
```
40+
/ralph-loop "Refactor the cache layer" --max-iterations 20
41+
/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"
42+
```
43+
44+
**Options:**
45+
- `--max-iterations <n>` - Max iterations before auto-stop
46+
- `--completion-promise <text>` - Promise phrase to signal completion
47+
48+
**How it works:**
49+
1. Creates `.claude/.ralph-loop.local.md` state file
50+
2. You work on the task
51+
3. When you try to exit, stop hook intercepts
52+
4. Same prompt fed back
53+
5. You see your previous work
54+
6. Continues until promise detected or max iterations
55+
56+
---
57+
58+
### /cancel-ralph
59+
60+
Cancel an active Ralph loop (removes the loop state file).
61+
62+
**Usage:**
63+
```
64+
/cancel-ralph
65+
```
66+
67+
**How it works:**
68+
- Checks for active loop state file
69+
- Removes `.claude/.ralph-loop.local.md`
70+
- Reports cancellation with iteration count
71+
72+
---
73+
74+
## Key Concepts
75+
76+
### Completion Promises
77+
78+
To signal completion, Claude must output a `<promise>` tag:
79+
80+
```
81+
<promise>TASK COMPLETE</promise>
82+
```
83+
84+
The stop hook looks for this specific tag. Without it (or `--max-iterations`), Ralph runs infinitely.
85+
86+
### Self-Reference Mechanism
87+
88+
The "loop" doesn't mean Claude talks to itself. It means:
89+
- Same prompt repeated
90+
- Claude's work persists in files
91+
- Each iteration sees previous attempts
92+
- Builds incrementally toward goal
93+
94+
## Example
95+
96+
### Interactive Bug Fix
97+
98+
```
99+
/ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --completion-promise "FIXED" --max-iterations 10
100+
```
101+
102+
You'll see Ralph:
103+
- Attempt fixes
104+
- Run tests
105+
- See failures
106+
- Iterate on solution
107+
- In your current session
108+
109+
## When to Use Ralph
110+
111+
**Good for:**
112+
- Well-defined tasks with clear success criteria
113+
- Tasks requiring iteration and refinement
114+
- Iterative development with self-correction
115+
- Greenfield projects
116+
117+
**Not good for:**
118+
- Tasks requiring human judgment or design decisions
119+
- One-shot operations
120+
- Tasks with unclear success criteria
121+
- Debugging production issues (use targeted debugging instead)
122+
123+
## Learn More
124+
125+
- Original technique: https://ghuntley.com/ralph/
126+
- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

‎plugins/ralph-wiggum/commands/ralph-loop.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: "Start Ralph Wiggum loop in current session"
3+
argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
4+
allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
5+
hide-from-slash-command-tool: "true"
6+
---
7+
8+
# Ralph Loop Command
9+
10+
Execute the setup script to initialize the Ralph loop:
11+
12+
```!
13+
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
14+
```
15+
16+
Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
17+
18+
CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

‎plugins/ralph-wiggum/hooks/hooks.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"description": "Ralph Wiggum plugin stop hook for self-referential loops",
3+
"hooks": {
4+
"Stop": [
5+
{
6+
"hooks": [
7+
{
8+
"type": "command",
9+
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
10+
}
11+
]
12+
}
13+
]
14+
}
15+
}

0 commit comments

Comments
 (0)