Harnesses > Autonomous loops
Ralph Loop
Draft. This entry has not been checked against its sources yet.
Anthropic's Claude Code plugin for Geoffrey Huntley's Ralph Wiggum technique, in which a Stop hook feeds the same prompt back to the agent each time it tries to finish, until it prints an agreed completion phrase or reaches an iteration limit.
| Maintainer | Anthropic (first written by Daisy Hollman); technique by Geoffrey Huntley |
|---|---|
| Category | Autonomous loops |
| Hosts | Claude Code |
| Components | 3 commands, 1 hooks |
| License | Apache-2.0 |
| Version | 1.0.0 |
| Source code | https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop |
| Website | none |
| Docs | none |
| DeepWiki | https://deepwiki.com/anthropics/claude-plugins-official |
| Last researched | 2026-09-28, at commit fa59bc9 |
Features
Definitions are on the compare page.
| Feature | Supported | Notes |
|---|---|---|
| Stages of work it covers | ||
| Brainstorming | no | No questioning step. You write the prompt and the completion criteria; the README gives advice on how. |
| Written plans | no | No plan file. The README suggests listing phases inside the prompt. Huntley's method, per the Ralph Playbook, keeps a plan file; this plugin does not. |
| Test first | no | Not required. One README example prompt asks for TDD. |
| Debugging process | no | The loop retries until a phrase appears. The README says it is not for production debugging. |
| Code review | no | |
| Verification | no | The Stop hook checks only for the exact promise text. Running tests is up to your prompt; the README recommends putting 'tests passing' in the completion criteria. |
| Learning capture | no | No lessons file. Between passes the agent sees only the conversation and the project's files and git history. |
| Branch to PR | no | No git steps. The agent reads git history but the plugin never commits or opens a PR. |
| How it runs | ||
| Single entry point | n/a | One workflow started by one command, so there is nothing to route between. |
| Automatic activation | no | No skills. A loop starts only when you run /ralph-loop. |
| Session-start hook | no | Its one hook is a Stop hook that re-feeds the prompt at the end of each turn while a loop is active. |
| Blocking hooks | yes | The Stop hook blocks the end of each turn until the promise text appears or the iteration limit is reached. |
| Subagents | no | |
| Parallel agents | no | |
| Git worktrees | no | |
| Adopting it | ||
| Multiple hosts | no | Claude Code only. Cursor publishes its own separate plugin, also named ralph-loop. |
| Per-project setup | yes | Install at project scope so it is enabled in the committed .claude/settings.json. Loop settings are passed per run. |
| Team extensions | no | Only the prompt and two flags per run. Changing behavior means editing the hook script. |
| No extra services | yes | Needs bash, jq, and perl. On Windows, Git Bash. |
How it works
The workflow
Geoffrey Huntley's original form of the technique is a shell loop that pipes the same prompt file into an agent CLI forever, for example while :; do cat PROMPT.md | claude ; done. Each pass is a new process with a fresh context, so the agent learns about earlier passes only from the files and git history they left behind.
The plugin moves that loop inside one Claude Code session:
- You run
/ralph-loop "<prompt>" --max-iterations 20 --completion-promise "DONE". A setup script writes the prompt, the settings, and the current session's id to.claude/ralph-loop.local.md, then prints the prompt and the completion rules. - The agent works on the task as it would in any turn.
- When the agent tries to end its turn, the Stop hook reads the state file. It does nothing in a session other than the one that started the loop. If the iteration limit is reached, or the agent's latest text contains
<promise>DONE</promise>with exactly that text, the hook deletes the state file and lets the turn end. - Otherwise the hook increments the iteration count and blocks the stop, with the original prompt as the reason. Claude Code passes the prompt back and the agent starts the next pass in the same conversation, seeing its earlier edits in the files and git history.
/cancel-ralphdeletes the state file, which ends the loop the next time the agent stops.
Both flags are optional. With neither, the loop has no end condition of its own ("No completion promise set - loop runs infinitely"). The README says to "Always rely on --max-iterations as your primary safety mechanism", because the promise is one exact string and cannot tell "done" from "blocked".
Since version 2.1.143, Claude Code limits how long a Stop hook can keep one turn going: "after stop hooks have continued the turn eight times in a row, Claude Code overrides the next block and ends the turn". This hook ignores the stop_hook_active flag that Claude Code provides for this situation, so with default settings one /ralph-loop run gets the first pass plus eight re-feeds. The state file is left in place, so the hook blocks again the next time the agent tries to stop, for example after your next message. Set CLAUDE_CODE_STOP_HOOK_BLOCK_CAP to a higher number, or to 0 to remove the limit, for longer loops. The plugin's documentation predates the limit and does not mention it.
Components
- 3 commands:
/ralph-loopruns the setup script and adds a rule about honest completion./cancel-ralphchecks for the state file, deletes it, and reports the iteration it stopped at.help(/ralph-loop:help) has the agent explain the technique. - 1 hook: Stop, running
hooks/stop-hook.sh, a 191-line bash script. - 1 script:
scripts/setup-ralph-loop.sh, which parses the arguments and writes the state file. - No skills, subagents, or MCP servers.
How it steers the agent
- The Stop hook. It keeps the agent working by blocking the end of the turn. Claude Code enforces this, not the model, up to the limit described above. Workflow harnesses such as Superpowers use hooks only to inject text.
- A text-only finish line. The hook takes the last text block the agent wrote, finds the first
<promise>tag in it, normalizes whitespace, and compares the result with the phrase you set. It runs no tests and checks nothing else. A pass that ends on a tool call with no text simply continues the loop. - Wording about honesty. The command says: "CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck". The setup output adds "Do NOT lie even if you think you should exit" and "Trust the process." Each re-fed prompt comes with a system message: "To stop: output <promise>DONE</promise> (ONLY when statement is TRUE - do not lie to exit!)".
- Everything else is your prompt. The README's advice covers clear completion criteria, work split into phases, test-and-fix steps, and instructions for what to do if stuck after a number of passes.
Files it writes
.claude/ralph-loop.local.md: the prompt, plus frontmatter holdingiteration,session_id,max_iterations,completion_promise, andstarted_at. It is deleted when the loop ends by promise, limit, cancel, or a hook error. The plugin does not add it to.gitignore.
It writes no plan, progress log, or lessons file. Between passes the agent has the conversation so far and whatever it wrote to the project. Huntley's method, as the Ralph Playbook describes it, keeps a plan file and an AGENTS.md for this. With the plugin, you would have to ask for such files in your prompt.
The state file sits in the project directory, but the hook compares the recorded session id with the session that is stopping and ignores other sessions. This check was added on 2026-03-02. A state file without an id, written by an older version, still applies to every session in the directory.
Install
In Claude Code:
/plugin install ralph-loop@claude-plugins-official
Claude Code adds Anthropic's official marketplace on first interactive start. To enable the plugin for a team, install at project scope so the entry goes in the committed .claude/settings.json. Each person still runs the install once. Needs bash, jq, and perl. On Windows it needs Git for Windows; the README explains how to point the hook at Git Bash when bash resolves to WSL.
The plugin was called ralph-wiggum until 2026-01-06, when Anthropic renamed it "to avoid trademark concerns". An older copy under that name is still in the anthropics/claude-code repository. It has the same commands, hook, and flags, but:
- It has not changed since 2026-01-06.
- It lacks the session check, so every session in the directory is held in the loop.
- It ends the loop if the last transcript line holds no text.
- It has no plugin license; the repository is "All rights reserved".
Cursor publishes its own implementation, also named ralph-loop, installed with /add-plugin ralph-loop. It was written separately, not converted from Anthropic's files, and it differs in these ways:
- It has three skills instead of commands, so you start it in plain language ("Start a ralph loop: ..."). The agent writes the state file,
.cursor/ralph/scratchpad.md, itself. - It uses two hooks. An
afterAgentResponsehook checks each response for the promise and writes adoneflag. Astophook sends the prompt back as a follow-up message, a new user message prefixed with the iteration number. - It sets
loop_limit: null, which removes Cursor's default limit of five automatic follow-ups. - The flags and promise matching are the same, but unlike Anthropic's plugin it does not check which session started the loop.
Community implementations, not researched here, include:
- Ralph Orchestrator, linked from both plugins' READMEs, which runs the loop across many agent CLIs.
- ralph-loop-quickstart, a shell loop with a fresh context each pass, "NOT using the Anthropic plugin".
- ralph-loop-agent, a library for the Vercel AI SDK.
When to choose it
- The task has a check the agent can run itself, such as a test suite, and you can write down what "done" means.
- You want to stay in one interactive session and watch the passes, rather than run a shell loop.
- You want something small enough to read in full: two bash scripts of 395 lines together and three short command files.
When not to
- Long runs. Context builds up across passes in one conversation, while Huntley's form starts each pass fresh. An open issue asks for fresh-context passes. For long unattended work, a shell loop or one of the community tools follows the original design.
- You need the loop to end on a checked condition. It ends when the model prints a phrase, and only wording asks the model not to print it early.
- You want a process: questions, a plan, tests first, review, or lessons. The plugin has none; your prompt has to supply them.
- You expect more than nine passes per run on default Claude Code settings. Raise
CLAUDE_CODE_STOP_HOOK_BLOCK_CAPfirst. - The README adds: tasks that need human judgment or design decisions, one-shot operations, and tasks with unclear success criteria.
Parts of the documentation do not match the code:
help.mdnames the state file.claude/.ralph-loop.local.md, with an extra dot.- The setup script says "This loop cannot be stopped manually!" although
/cancel-ralphworks. - The hook's header comment says it feeds the agent's output back, but it feeds the original prompt.
Sources
- anthropics/claude-plugins-official at fa59bc9:
README.md,LICENSE,commands/,hooks/,scripts/,.claude-plugin/plugin.json, and the repository'sREADME.mdand.claude-plugin/marketplace.json. This commit is the repository head on 2026-09-25, not a change to the plugin; the last commit touchingplugins/ralph-loop/is986deab(2026-03-28), and the session check is8644df9(2026-03-02). - Rename commit 44328be: "Rename ralph-wiggum plugin to ralph-loop per legal guidance"
- The older
ralph-wiggumcopy in anthropics/claude-code at 7779afb, compared file by file. The last commit touching it isc2022d3(2026-01-06). - Cursor's
ralph-loopin cursor/plugins at ecc249f - The Ralph Playbook, the source for Huntley's loop as quoted above
- Claude Code CHANGELOG, 2.1.143 entry: "the turn now ends with a warning after 8 consecutive blocks (override via
CLAUDE_CODE_STOP_HOOK_BLOCK_CAP)" - Claude Code docs: hooks reference, hooks guide, environment variables, discover plugins
- Plugin deviates from original Ralph behavior (context should be fresh each iteration)
- Ralph Wiggum as a "software engineer", Geoffrey Huntley (linked, not read: blocked from the research environment)
- Cursor hooks documentation (not read: blocked from the research environment; the
loop_limitdefault comes from a search result summary) - Ralph Orchestrator, ralph-loop-quickstart, ralph-loop-agent
- DeepWiki was not used: it was unreachable from the research environment.