ralph-loop

name	ralph-loop
description	Start a Ralph Loop for iterative self-referential development. Use when the user asks to run a ralph loop, start an iterative loop, or wants repeated autonomous iteration on a task until completion.

Ralph Loop

Trigger

The user wants to start a Ralph loop. An iterative development loop where the same prompt is fed back after every turn, and the agent sees its own previous work each iteration.

The 8-iteration ceiling (tell the user about this)

Claude Code ends a turn after 8 consecutive Stop-hook continuations. The cap is enforced by Claude Code itself and is not configurable, so a Ralph loop advances at most 8 iterations per user turn.

• max_iterations above 8 is still honoured, but it is spread across turns: the loop pauses at the ceiling and keeps its state.
• To resume, the user sends any message (for example continue). The counter resets and the loop runs up to 8 more iterations from the iteration it left off at.
• Always mention this when confirming a loop with max_iterations above 8, so the user is not surprised when the run pauses.
• For long unattended iteration, /loop is the Claude Code native alternative — it re-issues a prompt on an interval or self-paced, with no 8-continuation ceiling. Ralph is the better fit when you want the same prompt replayed against the agent's own accumulating work inside one turn.

Workflow

1. Gather the user's task prompt and optional parameters:

   • max_iterations (number, default 0 for unlimited)
   • completion_promise (text, or "null" if not set)

2. Create the directory .claude/ralph/ in the project root if it doesn't exist, then write the state file at .claude/ralph/scratchpad.md with this exact format:

   ---
   iteration: 1
   max_iterations: <N or 0>
   completion_promise: "<TEXT>" or null
   turn_continuations: 0
   ---
   
   <the user's task prompt goes here>
   

   Example:

   ---
   iteration: 1
   max_iterations: 20
   completion_promise: "COMPLETE"
   turn_continuations: 0
   ---
   
   Build a REST API for todos with CRUD operations, input validation, and tests.
   

   turn_continuations is bookkeeping for the 8-continuation ceiling. Always write it as 0; the hook maintains it.

3. Confirm to the user that the Ralph loop is active — prompt, iteration limit, promise if set, and the 8-iterations-per-turn ceiling if max_iterations is 0 or above 8. Then begin working on the task.

4. The Stop hook intercepts each turn end and feeds the same prompt back as a blocked-stop reason. You will see it prefixed with [Ralph loop iteration N.]. The final iteration of a turn is additionally marked as such.

Guardrails

• If a completion promise is set, you may ONLY output <promise>TEXT</promise> when the statement is completely and genuinely true.
• Do not output false promises to escape the loop.
• Do not write <promise>...</promise> speculatively mid-answer ("I'll output <promise>DONE</promise> when finished") — the hook reads the first promise tag in your final message and would end the loop early.
• Always recommend setting max_iterations as a safety net.
• Quote the completion_promise value in the YAML frontmatter if it contains special characters.

Output

Confirm the loop is active (prompt, iteration limit, promise if set, per-turn ceiling), then start working on the task immediately.