Ralph Loop

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.

This technique is inspired by the Ralph Wiggum coding technique (named after the character from The Simpsons), embodying the philosophy of persistent iteration despite setbacks.

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. The Stop hook in hooks/stop-hook.sh creates the self-referential feedback loop by blocking normal session exit.

This creates a self-referential feedback loop where:

• The prompt never changes between iterations
• Claude's previous work persists in files
• Each iteration sees modified files and git history
• Claude autonomously improves by reading its own past work in files

Quick Start

/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

Claude will:

• Implement the API iteratively
• Run tests and see failures
• Fix bugs based on test output
• Iterate until all requirements met
• Output the completion promise when done

Commands

/ralph-loop

Start a Ralph loop in your current session.

Usage:

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

Options:

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

/cancel-ralph

Cancel the active Ralph loop.

Usage:

/cancel-ralph

Prompt Writing Best Practices

1. Clear Completion Criteria

❌ Bad: "Build a todo API and make it good."

✅ Good:

Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>COMPLETE</promise>

2. Incremental Goals

❌ Bad: "Create a complete e-commerce platform."

✅ Good:

Phase 1: User authentication (JWT, tests)
Phase 2: Product catalog (list/search, tests)
Phase 3: Shopping cart (add/remove, tests)

Output <promise>COMPLETE</promise> when all phases done.

3. Self-Correction

❌ Bad: "Write code for feature X."

✅ Good:

Implement feature X following TDD:
1. Write failing tests
2. Implement feature
3. Run tests
4. If any fail, debug and fix
5. Refactor if needed
6. Repeat until all green
7. Output: <promise>COMPLETE</promise>

4. Escape Hatches

Always use --max-iterations as a safety net to prevent infinite loops on impossible tasks:

# Recommended: Always set a reasonable iteration limit
/ralph-loop "Try to implement feature X" --max-iterations 20

# In your prompt, include what to do if stuck:
# "After 15 iterations, if not complete:
#  - Document what's blocking progress
#  - List what was attempted
#  - Suggest alternative approaches"

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.