ralph-loop

Ralph Loop

Implementation of the Ralph Wiggum technique: a single prompt re-fed to Claude on every session-exit attempt via a Stop hook, until Claude emits an exact completion-promise string or max-iterations is reached.

Based on Anthropic's official ralph-loop plugin and Geoffrey Huntley's original technique.

Core concept

/ralph-loop "<prompt>" --completion-promise "DONE" --max-iterations 50

# Then Claude Code automatically:
# 1. Works on the task
# 2. Tries to exit
# 3. Stop hook (.claude/hooks/ralph-stop.sh) blocks exit
# 4. Hook checks transcript for completion-promise
# 5. If found → state cleared, exit allowed
# 6. If not + under budget → state incremented, exit blocked, prompt re-fed
# 7. If not + budget exhausted → state cleared, exit allowed with halt message

The loop is self-referential: the prompt never changes between iterations. Claude's previous work persists in files. Each iteration sees modified files and git history. The improvement comes from reading the result of the previous iteration.

When to use

Good for:

• Well-defined tasks with automatic verification (tests, linters, build, type-check)
• Tasks requiring iteration to refine (getting tests to pass, fixing a flaky integration)
• Greenfield projects you can walk away from
• Overnight unattended runs

Not good for:

• Tasks requiring human judgment or design decisions (use quality-review instead)
• One-shot operations
• Tasks without a clear binary signal for completion
• Production debugging (use /five-whys and the debugger agent)

State + safety

The Stop hook reads .ralph-loop/state.json:

{
  "prompt": "<the original prompt>",
  "completion_promise": "DONE",
  "max_iterations": 50,
  "current_iteration": 3,
  "started_at": "<iso8601>",
  "last_continued_at": "<iso8601>"
}

--max-iterations is the primary safety mechanism. The completion-promise uses exact-string matching so it cannot encode multiple completion conditions (no "SUCCESS" vs "BLOCKED"); always rely on max-iterations as the hard ceiling.