ralph-loop

name	ralph-loop
description	Activate autonomous Ralph Wiggum loop mode for iterative task completion. Use when you have a well-defined task with clear completion criteria that benefits from persistent, autonomous execution.
metadata	{"version":"1.0.0","tags":["automation","workflow","claude-code-only","hooks","autonomous"],"trigger":"When user invokes /ralph, mentions ralph mode, ralph loop, autonomous loop, or wants to run Claude iteratively until a task is complete"}

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:

---
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:

# 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.

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.

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

When Claude outputs <promise>feature implemented</promise>, the loop ends.

Configuration Options

In .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:

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

To stop immediately:

rm .claude/ralph-loop.local.md

To resume:

# 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

---
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:

# 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

1. Clear prompts reduce iterations by 40-60% - be specific
2. Start with small max_iterations (5-10) until confident
3. Git commit after every checkpoint - easy rollback
4. Use TODO.md completion - more reliable than promise tags
5. Monitor first few iterations - catch bad patterns early
6. 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

# 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