# Ralph Loop

> >

- **Type:** Skill
- **Install:** `agentstack add skill-carinyaparc-skills-ralph-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [carinyaparc](https://agentstack.voostack.com/s/carinyaparc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [carinyaparc](https://github.com/carinyaparc)
- **Source:** https://github.com/carinyaparc/skills/tree/main/skills/ralph-loop

## Install

```sh
agentstack add skill-carinyaparc-skills-ralph-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](../ralph-loop-setup/SKILL.md)**.
This skill assumes a seeded loop, except for a quick inline ad-hoc start.

## How the loop works

1. `/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.
2. `/ralph-loop start` verifies the seeded files and executes iteration 1.
3. 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.
4. The loop ends when the agent emits `TEXT` 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](references/loop-protocol.md) — the step machine, budgets, guardrails, and why one step per iteration
- [references/preset-authoring.md](references/preset-authoring.md) — how to write a preset, with a worked non-engineering example
- [references/prompt-authoring.md](references/prompt-authoring.md) — completion promises, iteration budgets, escape hatches

## Assets

- [assets/loop.core.template.md](assets/loop.core.template.md) — generic loop body, preset-agnostic
- [assets/loop-state.core.template.md](assets/loop-state.core.template.md) — per-run mutable state
- [assets/context.core.template.md](assets/context.core.template.md) — per-run static context
- [assets/presets/](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](prompts/start.prompt.md). Verify the
seeded loop, confirm the branch where the preset needs one, execute iteration
1. With `--prompt "..."` and no seeded loop, seed an ad-hoc loop first.

**status** — [prompts/status.prompt.md](prompts/status.prompt.md). Report
iteration, current step, budgets used, completed items, and artefacts.
Read-only.

**cancel** — [prompts/cancel.prompt.md](prompts/cancel.prompt.md). Stop the
loop and archive the run directory as a record.

## Ground rules

- Only output `TEXT` 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [carinyaparc](https://github.com/carinyaparc)
- **Source:** [carinyaparc/skills](https://github.com/carinyaparc/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-carinyaparc-skills-ralph-loop
- Seller: https://agentstack.voostack.com/s/carinyaparc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.