Ralph Wiggum Loop Mode

Named after the Simpsons character who "never stops despite being confused," this technique runs Claude Code in a loop where the prompt stays the same but the codebase accumulates changes. Each iteration reads previous work and continues until completion.

When to Use Ralph Mode

Ideal for:

Well-defined implementation tasks with clear completion criteria
Refactoring or migration work (e.g., React v16 to v19)
Test-driven development cycles (run until tests pass)
Batch processing or repetitive tasks
Overnight autonomous work sessions

Not ideal for:

Tasks requiring design decisions or human judgment
Exploratory work without clear end states
Tasks where requirements may change mid-execution
First-time implementations where you need to learn the code

Activation Protocol

Step 1: Validate Task Suitability

Before activating, confirm:

Task has clear, measurable completion criteria
Success can be verified programmatically (tests, build, specific file state)
The work is in a git-tracked directory
You understand what success looks like

Step 2: Create State File

Create

.claude/ralph-loop.local.md

with the following structure:

markdown

---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---

# Your Task Prompt Here

## Objective
[Clear statement of what needs to be accomplished]

## Completion Criteria
Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

## Verification Commands
Run these to check progress:
- `[test command]`
- `[build command]`

## Context
- Read [relevant files] for specifications
- Follow [conventions file] for code style

Step 3: Create TODO.md (Recommended Completion Method)

Create

TODO.md

in your project root:

markdown

# Task Checklist

## Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Completion
- [ ] ALL_TASKS_COMPLETE

Step 4: Start the Loop

Simply run Claude normally. The Stop hook will detect the state file and keep the loop running until completion is detected.

bash

claude

Two Completion Methods

Method 1: TODO.md Markers (Recommended)

The hook checks

TODO.md

for

[x] ALL_TASKS_COMPLETE

. This is more reliable because:

It's visible in the file system
It can be tracked in git
Claude can easily update it
You can see progress (X/Y tasks complete)

Method 2: Promise Tags (Legacy)

Set

completion_promise

in the state file and output

<promise>YOUR_TEXT</promise>

when complete.

markdown

---
active: true
iteration: 0
max_iterations: 20
completion_promise: "feature implemented"
---

When Claude outputs

<promise>feature implemented</promise>

, the loop ends.

Configuration Options

.claude/ralph-loop.local.md

frontmatter:

Option	Default	Description
`active`	`true`	Set to `false` to disable loop
`iteration`	`0`	Current iteration count (auto-incremented)
`max_iterations`	`20`	Safety cap (0 = unlimited)
`completion_promise`	`null`	Text to match for promise completion

During Execution

Iteration Status

Every iteration shows:

Current iteration number
Task progress (from TODO.md)
Completion criteria
Max iterations remaining

Checkpoint Notifications

Every 5 iterations, you'll see a checkpoint reminder to:

Review changes:
```
git log --oneline -10
```
Verify progress is on track
Consider adjusting the prompt if stuck

Manual Intervention

To pause the loop:

bash

# Edit the state file
# Change active: true → active: false

To stop immediately:

bash

rm .claude/ralph-loop.local.md

To resume:

bash

# Re-create or edit the state file
# Set active: true
claude

Safety Features

Iteration cap: Prevents infinite loops (default: 20)
Git tracking: Every change is revertible
Checkpoint notifications: Reminders to review progress
Clear completion criteria: Loop only exits on explicit success
Cost awareness: Track iterations to estimate API costs

Example: MetricFlow Phase 7-8

markdown

---
active: true
iteration: 0
max_iterations: 25
completion_promise: null
---

# MetricFlow Phase 7-8: Educator Agent

## Objective
Implement the Educator Agent that uses Claude API to generate educational
explanations for code metrics.

## Completion Criteria
Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

## Verification Commands
- `cd backend && python -m pytest tests/test_educator.py -v`
- `cd backend && python -c "from app.agents.educator import EducatorAgent; print('OK')"`

## Context
- Read docs/plans/MASTER_PLAN.md sections 5.3 (Educator Agent)
- Follow CLAUDE.md for project conventions
- Analyzer and Pattern agents already complete (use their output formats)

## Instructions
1. Check TODO.md for current task list
2. Implement next incomplete task
3. Write tests as you go
4. Run verification after each change
5. Mark [x] ALL_TASKS_COMPLETE when done

And corresponding

TODO.md

markdown

# Phase 7-8: Educator Agent

## Tasks
- [ ] Create EducatorAgent class skeleton in backend/app/agents/educator.py
- [ ] Add Claude API client initialization
- [ ] Implement explain_complexity() method
- [ ] Implement explain_maintainability() method
- [ ] Implement explain_code_smells() method
- [ ] Add course concept mapping
- [ ] Write unit tests for all methods
- [ ] Integration test with Analyzer output

## Completion
- [ ] ALL_TASKS_COMPLETE

Troubleshooting

Loop won't start:

Check
```
.claude/ralph-loop.local.md
```
exists
Verify
```
active: true
```
is set in frontmatter

Loop won't stop:

Ensure TODO.md contains exactly
```
[x] ALL_TASKS_COMPLETE
```
(case-insensitive)
Or check
```
completion_promise
```
matches your output tag
Check
```
max_iterations
```
isn't set to 0 (unlimited)
Manual stop:
```
rm .claude/ralph-loop.local.md
```

Stuck on same error:

Review the error pattern
Adjust the prompt with more specific guidance
Consider breaking task into smaller subtasks

Costs too high:

Reduce
```
max_iterations
```
Use shorter checkpoint intervals for early review
Consider if task is too complex for Ralph mode

Tips for Success

Clear prompts reduce iterations by 40-60% - be specific
Start with small max_iterations (5-10) until confident
Git commit after every checkpoint - easy rollback
Use TODO.md completion - more reliable than promise tags
Monitor first few iterations - catch bad patterns early
Supervised autonomy - review at checkpoints for course projects

Cost Estimates

Task Complexity	Iterations	Estimated Cost
Simple (single feature)	5-10	$5-15
Medium (multi-file changes)	10-20	$15-30
Complex (full phase)	20-50	$30-75

Quick Start Template

bash

# 1. Create state file
mkdir -p .claude
cat > .claude/ralph-loop.local.md << 'EOF'
---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---

# Your Task

## Objective
[What you want to accomplish]

## Completion
Check TODO.md for [x] ALL_TASKS_COMPLETE
EOF

# 2. Create TODO.md
cat > TODO.md << 'EOF'
# Tasks
- [ ] First task
- [ ] Second task

## Completion
- [ ] ALL_TASKS_COMPLETE
EOF

# 3. Start Ralph loop
claude

ralph-loop

NPX Install

Tags

SKILL.md Content

Ralph Wiggum Loop Mode

When to Use Ralph Mode

Activation Protocol

Step 1: Validate Task Suitability

Step 2: Create State File

Step 3: Create TODO.md (Recommended Completion Method)

Step 4: Start the Loop

Two Completion Methods

Method 1: TODO.md Markers (Recommended)

Method 2: Promise Tags (Legacy)

Configuration Options

During Execution

Iteration Status

Checkpoint Notifications

Manual Intervention

Safety Features

Example: MetricFlow Phase 7-8

Troubleshooting

Tips for Success

Cost Estimates

Quick Start Template