ralph-loop

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

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

[Clear statement of what needs to be accomplished]

Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

Run these to check progress:

• [test command]
• [build command]

• 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

• [ ] Task 1
• [ ] Task 2
• [ ] Task 3

• [ ] 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

```

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 YOUR_TEXT when complete.

```markdown

---

active: true

iteration: 0

max_iterations: 20

completion_promise: "feature implemented"

---

```

When Claude outputs feature implemented, the loop ends.

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 |

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

```

• 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

```markdown

---

active: true

iteration: 0

max_iterations: 25

completion_promise: null

---

# MetricFlow Phase 7-8: Educator Agent

Implement the Educator Agent that uses Claude API to generate educational

explanations for code metrics.

Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

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

• 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)

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

• [ ] 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

• [ ] ALL_TASKS_COMPLETE

```

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

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

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

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

[What you want to accomplish]

Check TODO.md for [x] ALL_TASKS_COMPLETE

EOF

# 2. Create TODO.md

cat > TODO.md << 'EOF'

# Tasks

• [ ] First task
• [ ] Second task

• [ ] ALL_TASKS_COMPLETE

EOF

# 3. Start Ralph loop

claude

```