Ralph loop
Run an autonomous loop. The plugin's stop hook re-feeds the loop prompt after
every turn, the agent executes exactly one step per iteration, and the loop
ends only when the completion promise is genuinely true or a safety rail
fires.
Seeding is a separate skill: ralph-loop-setup.
This skill assumes a seeded loop, except for a quick inline ad-hoc start.
How the loop works
/ralph-loop-setup resolves configuration and runs
scripts/seed-ralph-loop.sh, which writes {base}/active.md plus a run
directory. {base} is .claude/loop or .cursor/loop, resolved from the
agent, with no pointer file./ralph-loop start verifies the seeded files and executes iteration 1.- The plugin hooks take over. After every turn the stop hook re-feeds the body
of
active.md; the agent reads its own state and runs the next step.
- The loop ends when the agent emits
<promise>TEXT</promise> matching the
configured promise, max_iterations is reached, the 200-iteration hard
ceiling is hit, or the stall guard sees no state change for 3 consecutive
iterations.
Safety rails
| Rail |
Default |
Enforced by |
| max_iterations |
50 |
stop hook, from frontmatter |
| hard ceiling |
200 |
stop hook, applies even when unlimited |
| stall guard |
3 unchanged iterations |
stop hook, watches the state file |
| session isolation |
owning session only |
stop hook, from session_id |
| fix budgets |
per preset |
loop state counters |
Exhausting a budget never fails the loop: the step advances and the unresolved
findings are recorded under ## Notes so a human sees them.
References
- references/loop-protocol.md — the step machine, budgets, guardrails, and why one step per iteration
- references/preset-authoring.md — how to write a preset, with a worked non-engineering example
- references/prompt-authoring.md — completion promises, iteration budgets, escape hatches
Assets
- assets/loop.core.template.md — generic loop body, preset-agnostic
- assets/loop-state.core.template.md — per-run mutable state
- assets/context.core.template.md — per-run static context
- assets/presets/ —
engineering-delivery, ad-hoc, custom
Router
Mode is start, status, or cancel. If no mode is given: a seeded
{base}/active.md implies start; otherwise say the loop needs seeding and
point at /ralph-loop-setup.
start — prompts/start.prompt.md. Verify the
seeded loop, confirm the branch where the preset needs one, execute iteration
- With
--prompt "..." and no seeded loop, seed an ad-hoc loop first.
status — prompts/status.prompt.md. Report
iteration, current step, budgets used, completed items, and artefacts.
Read-only.
cancel — prompts/cancel.prompt.md. Stop the
loop and archive the run directory as a record.
Ground rules
- Only output
<promise>TEXT</promise> when the statement is completely and
genuinely true. Never to escape the loop, never because progress is slow.
- Exactly ONE step per iteration. State lives in files, not in memory.
- Every skill step runs in a fresh sub-agent. Context isolation per step is
what keeps a long run sharp.
- Where a preset commits, verify the branch with
git branch --show-current
first. No Co-authored-by trailers, no emojis in commits.
- If the external
ralph-loop-plugin is installed, disable it. This plugin
ships its own hooks and running both double-fires the stop hook.
1---2name: ralph-loop3description: Use to start, inspect, or stop a Ralph loop: an autonomous self-referential loop where a stop hook re-feeds the same prompt every turn until a completion promise is emitted or a safety rail fires (ralph-loop start, ralph-loop status, ralph-loop cancel). Works for any repeating multi-step job via presets, including full work-item delivery through implement, review, validate, and merge request. Do NOT use to seed or configure a loop (ralph-loop-setup), implement a single task once (implement), review a diff (code-review), or sign off a work item (validate) — the loop orchestrates those skills.4license: MIT5---67# Ralph loop89Run an autonomous loop. The plugin's stop hook re-feeds the loop prompt after10every turn, the agent executes exactly one step per iteration, and the loop11ends only when the completion promise is genuinely true or a safety rail12fires.1314Seeding is a separate skill: **[ralph-loop-setup](../ralph-loop-setup/SKILL.md)**.15This skill assumes a seeded loop, except for a quick inline ad-hoc start.1617## How the loop works18191. `/ralph-loop-setup` resolves configuration and runs20 `scripts/seed-ralph-loop.sh`, which writes `{base}/active.md` plus a run21 directory. `{base}` is `.claude/loop` or `.cursor/loop`, resolved from the22 agent, with no pointer file.232. `/ralph-loop start` verifies the seeded files and executes iteration 1.243. The plugin hooks take over. After every turn the stop hook re-feeds the body25 of `active.md`; the agent reads its own state and runs the next step.264. The loop ends when the agent emits `<promise>TEXT</promise>` matching the27 configured promise, `max_iterations` is reached, the 200-iteration hard28 ceiling is hit, or the stall guard sees no state change for 3 consecutive29 iterations.3031## Safety rails3233| Rail | Default | Enforced by |34| ---- | ------- | ----------- |35| max_iterations | 50 | stop hook, from frontmatter |36| hard ceiling | 200 | stop hook, applies even when unlimited |37| stall guard | 3 unchanged iterations | stop hook, watches the state file |38| session isolation | owning session only | stop hook, from `session_id` |39| fix budgets | per preset | loop state counters |4041Exhausting a budget never fails the loop: the step advances and the unresolved42findings are recorded under `## Notes` so a human sees them.4344## References4546- [references/loop-protocol.md](references/loop-protocol.md) — the step machine, budgets, guardrails, and why one step per iteration47- [references/preset-authoring.md](references/preset-authoring.md) — how to write a preset, with a worked non-engineering example48- [references/prompt-authoring.md](references/prompt-authoring.md) — completion promises, iteration budgets, escape hatches4950## Assets5152- [assets/loop.core.template.md](assets/loop.core.template.md) — generic loop body, preset-agnostic53- [assets/loop-state.core.template.md](assets/loop-state.core.template.md) — per-run mutable state54- [assets/context.core.template.md](assets/context.core.template.md) — per-run static context55- [assets/presets/](assets/presets/) — `engineering-delivery`, `ad-hoc`, `custom`5657## Router5859Mode is `start`, `status`, or `cancel`. If no mode is given: a seeded60`{base}/active.md` implies `start`; otherwise say the loop needs seeding and61point at `/ralph-loop-setup`.6263**start** — [prompts/start.prompt.md](prompts/start.prompt.md). Verify the64seeded loop, confirm the branch where the preset needs one, execute iteration651. With `--prompt "..."` and no seeded loop, seed an ad-hoc loop first.6667**status** — [prompts/status.prompt.md](prompts/status.prompt.md). Report68iteration, current step, budgets used, completed items, and artefacts.69Read-only.7071**cancel** — [prompts/cancel.prompt.md](prompts/cancel.prompt.md). Stop the72loop and archive the run directory as a record.7374## Ground rules7576- Only output `<promise>TEXT</promise>` when the statement is completely and77 genuinely true. Never to escape the loop, never because progress is slow.78- Exactly ONE step per iteration. State lives in files, not in memory.79- Every skill step runs in a fresh sub-agent. Context isolation per step is80 what keeps a long run sharp.81- Where a preset commits, verify the branch with `git branch --show-current`82 first. No `Co-authored-by` trailers, no emojis in commits.83- If the external `ralph-loop-plugin` is installed, disable it. This plugin84 ships its own hooks and running both double-fires the stop hook.
carinyadigital