ralph-loop-help

name	ralph-loop-help
description	Explain the Ralph Loop plugin, how it works, and available skills. Use when the user asks for help with ralph loop, wants to understand the technique, or needs usage examples.

Ralph Loop Help

Trigger

The user asks what Ralph Loop is, how it works, or needs usage guidance.

What to Explain

What is Ralph Loop?

Ralph Loop implements the Ralph Wiggum technique — an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.

Core concept: the same prompt is fed to the agent repeatedly. The "self-referential" aspect comes from the agent seeing its own previous work in the files and git history, not from feeding output back as input.

Each iteration:

1. The agent receives the SAME prompt
2. Works on the task, modifying files
3. Tries to finish the turn
4. The Stop hook intercepts and feeds the same prompt again
5. The agent sees its previous work in the files
6. Iteratively improves until completion

The 8-iteration-per-turn ceiling

Claude Code stops honouring Stop-hook continuations after 8 consecutive continuations in one turn. This is enforced by Claude Code and cannot be raised or disabled.

What that means in practice:

• A loop advances at most 8 iterations per user turn.
• max_iterations: 50 is not wrong, it just takes several turns to get there.
• When the ceiling is hit the loop pauses, it does not end. The state file is preserved and the iteration count is kept.
• Any next message from the user (continue works fine) resets the per-turn counter and runs up to 8 more iterations.
• The last iteration of each turn is marked in the injected prompt, so the agent knows to summarise its state before handing control back.

If the user wants genuinely long unattended iteration, point them at /loop, the Claude Code native alternative: it re-runs a prompt or slash command on an interval (or self-paced) with no continuation ceiling. Ralph is still the better tool when the point is to replay the same prompt against the agent's own accumulating work inside a single turn.

Starting a Ralph Loop

Tell the agent your task along with options:

Start a ralph loop: "Build a REST API for todos" --max-iterations 20 --completion-promise "COMPLETE"

Options:

• --max-iterations N — max iterations before auto-stop
• --completion-promise "TEXT" — phrase to signal completion

How it works:

1. Creates the .claude/ralph/scratchpad.md state file
2. Agent works on the task
3. The Stop hook intercepts the end of the turn and feeds the same prompt back
4. Agent sees its previous work and iterates
5. Continues until the promise is detected, max iterations is reached, or the per-turn ceiling pauses it

Cancelling a Ralph Loop

Ask the agent to cancel the ralph loop. It will remove the state file and report the iteration count. A paused loop is still an active loop — cancel it if you do not want the next message to resume it.

Completion Promises

To signal completion, the agent outputs a <promise> tag in its final message:

<promise>TASK COMPLETE</promise>

The Stop hook reads the agent's final message directly (Claude Code hands it to the hook as last_assistant_message) and looks for that specific tag. Because it matches the first promise tag in the message, the agent should never write the tag speculatively — only when the statement is genuinely true.

Without a promise (or --max-iterations), Ralph keeps going until it hits the per-turn ceiling, and resumes on every subsequent message until cancelled.

When to Use Ralph

Good for:

• Well-defined tasks with clear success criteria
• Tasks requiring iteration and refinement
• Iterative development with self-correction
• Greenfield projects

Not good for:

• Tasks requiring human judgment or design decisions
• One-shot operations
• Tasks with unclear success criteria
• Very long unattended runs — use /loop instead

Learn More

• Original technique: https://ghuntley.com/ralph/
• Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

Output

Present the above information clearly to the user, tailored to their specific question.