# ralph-loop

A skill that keeps feeding the same prompt back to the agent after every turn, so each pass builds on the previous one.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1000 installs · ★ 14099
- Author: cursor
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cursor/plugins/tree/HEAD/ralph-loop/skills/ralph-loop/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/ralph-loop

## What it does

Ralph Loop turns a single request into a repeating cycle. When a turn ends, the agent gets the same prompt again and can read what it produced last time, so work continues instead of restarting. Useful for tasks too large to finish in one pass.

The skill writes a state file at `.cursor/ralph/scratchpad.md`, creating the `.cursor/ralph/` directory first. Its YAML header holds the iteration number, `max_iterations`, and `completion_promise`; your task prompt sits underneath. A stop hook does the looping: it catches the end of each turn and re-sends the prompt as a followup message tagged `[Ralph loop iteration N.]`.

\`max_iterations` defaults to 0, which means no cap. The skill recommends setting a limit anyway as a safety net. The only clean way out is `<promise>TEXT</promise>`, and it should appear when the condition is genuinely met — not as an escape hatch. Put the `completion_promise` value in quotes if it contains special characters.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill ralph-loop -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ralph-loop/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ralph-loop/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill ralph-loop -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ralph-loop/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill ralph-loop -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ralph-loop/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cursor/plugins ralph-loop
```

2. **Manually: put the files in place**
- File: `.github/skills/ralph-loop/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill ralph-loop -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cursor/plugins --path ralph-loop/skills/ralph-loop
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ralph-loop/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill ralph-loop -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cursor/plugins/tree/HEAD/ralph-loop/skills/ralph-loop/SKILL.md

## When to use it
- push a large task through many agent passes to completion
- keep context across iterations of the same job
- define a stop condition instead of looping forever
- cap the number of iterations so the agent does not spin
- run unattended refinement from one prompt

## Example prompts
- Start a ralph loop to build a REST API for todos with CRUD, validation and tests, max 20 iterations, completion promise COMPLETE
- Run a ralph loop on the payments module refactor with no iteration limit
- Start an iterative loop to fix the failing tests in `tests/api`, stop on promise DONE

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

From the same set: [cursor/plugins](https://affpapa.org/en/nevibecode/by/cursor/plugins.md) — 47 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md