The Ralph loop: fresh context every iteration

You have a big, well-specified job — a migration, a port, a feature with forty pieces — and you are running it as one long session. Around the third hour the session is mostly its own history: earlier failed approaches, files read twice, a compaction summary standing in for the reasoning that produced the current state. Quality drops and you cannot say exactly when it started dropping.

The Ralph technique, named by Geoffrey Huntley, inverts the instinct that got you there. Stop trying to carry state forward. Put the state on disk, and run a loop where every iteration begins with an empty context window, does exactly one thing, and dies.

#!/usr/bin/env bash
# ralph.sh — run as: bash ralph.sh
while :; do
  cat PROMPT.md | claude -p \
    --allowedTools "Read,Edit,Bash(npm test),Bash(git commit *)"
done

The loop is not there to remember. It is there to guarantee that nothing is remembered.

What has to live in PROMPT.md

The prompt file is the whole design. It is re-read verbatim on every iteration, so anything not written there does not exist. Huntley's named failure modes map almost one-to-one onto lines the file has to carry:

It also has to define what counts as validation — compiles, tests pass, lints clean — because otherwise "looks done" is the only signal the agent has. That part the docs agree with: the glossary defines a verification loop as the prerequisite for unattended runs, since without one "the only thing deciding the agent is finished is the agent itself."

How this differs from the loops Claude Code ships

Three built-ins look like this and are not:

/goal is the closest built-in answer to "keep going until it's right," and with -p it runs the loop to completion in a single invocation — one context, many turns. That is the opposite trade from Ralph. /batch is the closest in spirit: independent fresh contexts, one unit of work each. The gap Ralph fills is sequential work where iteration N+1 depends on N having landed, which fan-out cannot express.

What the docs do and do not back

The mechanism is entirely documented. The best-practices page shows the shell loop over claude -p with --allowedTools scoping for unattended runs, and it recommends writing a spec to a file and then starting a fresh session to execute it — spec on disk, clean context, exactly Ralph's move performed once by hand. It also states the underlying principle outright: a clean session with a better prompt almost always outperforms a long session with accumulated corrections.

What no page says is that you should do this on repeat, without supervision, as the way you build a feature. Nor do the docs anywhere mention the duplicate-implementation failure mode, which is the single most useful thing in Huntley's writeup and the one you will hit first.

What is unverified here

Nobody has run this and measured it. Specifically:

• The economics are self-reported. A $50,000 contract delivered for $297 of tokens is one person's anecdote about one project, with no baseline for what the same work cost in a normal session. Treat it as evidence the technique is not absurd, not as a cost model.
• "Beats one long session" is untested. There is no A/B anywhere — same spec, same repo, loop versus session, quality and cost compared. That comparison is the experiment that would settle this, and it is cheap to run on a small feature.
• Iteration count is unbounded by design. The loop has no completion condition. You decide it is done by looking, which reintroduces the human in the place the technique claims to remove them.

Huntley is himself explicit that there is no perfect prompt — the loop, not the wording, is the artefact you are engineering. Which is a nice way of saying the technique's value is a claim about process, and process claims are the hardest kind to check.