Ralph Loops

A Ralph loop repeatedly starts an agent on a task and often gives each attempt a fresh context. The requirements and progress live outside the conversation. So does the evidence, letting the next session continue the work.

The Minimum Useful Loop

A minimal useful loop loads the requirement and current run state, then repeats while work remains and the limits allow another attempt:

• Select one unfinished task.
• Start a fresh agent with the relevant context.
• Inspect the resulting artifact.
• Run the required checks.
• Record the evidence and update progress.

It stops with a verified result or a specific unresolved failure.

The name covers several implementations. A simple shell loop may only repeat a prompt. A reliable engineering workflow adds completion checks and bounded attempts, plus durable state. A checked box the agent wrote is a progress claim that still needs evidence.

How The Loop Keeps State

The original Ralph loop, also called the Ralph Wiggum technique, is a shell loop around a headless agent. Each pass starts claude -p with the same prompt file. The agent reads a plan file for what to build and an implementation file with a checkbox per task. It completes the next unchecked task and ticks its box before exiting. The loop stops when no boxes remain.

The checkboxes and the Git history carry state between passes. Every pass starts with a fresh context, so each one works with the focus of a short session. Coherence comes from the files the loop rereads on every pass rather than from the conversation.

Carry Forward The Useful State

Each attempt needs the current requirement and the workspace, plus any relevant decisions. It also needs the previous failure and the next task. Large plan files can themselves become a context burden. Split project documentation by responsibility and retrieve the relevant portion for each stage.

A fresh context removes accumulated conversation noise. It also removes details unless you saved and supplied them again. Inspect the handoff rather than assuming a reset improves every task.

Stop Repeating Unproductive Attempts

Set an attempt limit and elapsed-time limit, plus a usage budget where the runner can measure it. Detect repeated failures and stop when another implementation attempt would not address the cause. Missing credentials and unresolved product decisions require different responses from failing tests.

Retrying a stage that created an external resource can duplicate the action. Reconcile recorded state with the external system or use an idempotency key before retrying.

Where Plain Loops Break

A bare Ralph loop has no gates. A broken change can pass through many iterations before anyone sees it. Code can end up built but never wired in, or written twice because one pass missed the work of another. On a large project the plan files themselves grow until they crowd the context they were meant to save.

Each fix for these problems adds structure. A gate after each pass catches a broken build early. A repair attempt with the failure log as input comes next, and a person takes over after a set number of tries. Replace the static plan files with per-stage requirements and on-demand specifications once the project outgrows them. At that point the loop has become a full pipeline.

Exercise 11: Build A Ralph Loop

Start a new Git project for a small command-line tool. Write a plan file describing what the tool does and an implementation file with five tasks, each with a checkbox. Then write a shell loop that runs claude -p once per pass. Each pass reads both files, completes the next unchecked task, ticks its box, and exits. Stop the loop after eight passes even if boxes remain.

Add a step after each pass that runs the tests and ends the loop on a failure. Let it run unattended, then read the Git history from start to finish. Look for code that was written but never connected to anything and for functions that appear twice. Note which files carried progress from one pass to the next, since no pass could see the conversation of the one before it.

September, 2026