The Ralph Loop, Explained: An Autonomous AI Coding Technique

What Is the Ralph Loop?

The Ralph loop — often called the "Ralph Wiggum" technique — is one of the most-copied patterns in loop engineering. The idea, credited to developer Geoffrey Huntley, is almost embarrassingly simple: put a coding agent in a bash loop, give it a state file to read, and let it restart from scratch every single iteration until the work is done.

No orchestration framework, no persistent conversation, no complex agent memory system. Just a loop, a spec, and a fresh start every time.

How It Works

A Ralph loop has three moving parts:

1. A state file on disk — usually a task list, a spec, or a progress log (prd.json, progress.md, and similar). This is the agent's only memory between iterations; nothing lives in a chat thread.
2. A restart, not a resume. Each iteration spins up a brand-new agent session. It reads the state file, picks the next well-scoped item, implements it, runs the project's real test/lint/build commands, commits, and updates the state file before exiting.
3. A shell loop that keeps restarting it. When the process exits, the loop starts again — new session, same state file, next item.

The "fresh context every time" part is the whole point. Long agent sessions accumulate context rot: old mistakes, stale assumptions, and irrelevant history that quietly degrades output quality the longer a session runs. Ralph sidesteps that by never letting a session get long enough to rot — it burns through exactly one task, records what happened, and starts clean.

Ralph vs. Ordinary Prompting

A normal coding-agent session is a conversation: you type, it responds, you correct it, back and forth in one continuous context window. A Ralph loop replaces that conversation with a contract — a state file both you and the agent read and write to — and lets a dumb shell loop do the "keep going" part a human would otherwise do by hand.

That trade only works if the tasks in the state file are genuinely well-scoped. A vague or oversized task will make every fresh-context iteration guess at scope differently, which is the most common way Ralph loops go sideways in practice.

A Ralph Loop You Can Run Today

Ralph Story Executor on MCP.so is a direct implementation of the technique: it reads incomplete stories from a .ralph/prd.json file, implements exactly one story per pass with minimal scope, runs the project's test/lint/build commands as backpressure, commits with a story-scoped message, and records what it learned in .ralph/progress.md before the next iteration starts. It exits only once every story in the file is marked complete.

A closely related pattern, Guardrails Learning Loop, adds one more piece of state to the same .ralph/ directory: when a check fails the same way twice, the loop writes a standing rule to .ralph/guardrails.md so every future iteration — fresh context and all — automatically respects it.

Related Patterns

Ralph isn't the only named loop pattern worth knowing:

• Reflexion loops keep a short-lived reflection instead of a long-lived plan — the agent writes down what went wrong after each failed attempt and reads it back before retrying. See Reflexion Debug Loop.
• Most other loops in the MCP.so Loops directory don't restart context between iterations at all — they're single well-scoped prompts with a check command and exit condition, which is the simpler end of the loop-engineering spectrum. Ralph is what you reach for once a task is too large for one prompt but too repetitive to babysit by hand.

If you're new to the broader idea, start with What Is Loop Engineering? for the four-part anatomy every loop — Ralph included — is built from.