agentharnesses.dev

A field guide to agentic coding harnesses, for teams that have been told to adopt one.


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.

MaintainerAnthropic (first written by Daisy Hollman); technique by Geoffrey Huntley
CategoryAutonomous loops
HostsClaude Code
Components3 commands, 1 hooks
LicenseApache-2.0
Version1.0.0
Source codehttps://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop
Websitenone
Docsnone
DeepWikihttps://deepwiki.com/anthropics/claude-plugins-official
Last researched2026-09-28, at commit fa59bc9

Features

Definitions are on the compare page.

FeatureSupportedNotes
Stages of work it covers
BrainstormingnoNo questioning step. You write the prompt and the completion criteria; the README gives advice on how.
Written plansnoNo 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 firstnoNot required. One README example prompt asks for TDD.
Debugging processnoThe loop retries until a phrase appears. The README says it is not for production debugging.
Code reviewno
VerificationnoThe 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 capturenoNo lessons file. Between passes the agent sees only the conversation and the project's files and git history.
Branch to PRnoNo git steps. The agent reads git history but the plugin never commits or opens a PR.
How it runs
Single entry pointn/aOne workflow started by one command, so there is nothing to route between.
Automatic activationnoNo skills. A loop starts only when you run /ralph-loop.
Session-start hooknoIts one hook is a Stop hook that re-feeds the prompt at the end of each turn while a loop is active.
Blocking hooksyesThe Stop hook blocks the end of each turn until the promise text appears or the iteration limit is reached.
Subagentsno
Parallel agentsno
Git worktreesno
Adopting it
Multiple hostsnoClaude Code only. Cursor publishes its own separate plugin, also named ralph-loop.
Per-project setupyesInstall at project scope so it is enabled in the committed .claude/settings.json. Loop settings are passed per run.
Team extensionsnoOnly the prompt and two flags per run. Changing behavior means editing the hook script.
No extra servicesyesNeeds 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:

  1. 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.
  2. The agent works on the task as it would in any turn.
  3. 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.
  4. 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.
  5. /cancel-ralph deletes 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

How it steers the agent

Files it writes

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:

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:

Community implementations, not researched here, include:

When to choose it

When not to

Parts of the documentation do not match the code:

Sources