Most developers treat AI coding like a chat interface: prompt, watch, and intervene when it loses the thread. This human-in-the-loop (HITL) approach is fine for prototypes, but it fails on complex features.
The Ralph Loop is a technique for running AI coding agents in a simple bash loop to achieve autonomous, unsupervised work.
It solves the "implicit execution budget" problem, where an AI declares a job "done" even if the tests are still red.
You use a loop because AI has no taste, and it will lie to you about tests passing if you let it. The bigger win is that it solves "context rot." Long sessions don't just fill up the window; the model starts to summarize or "compact" history, losing your critical initial instructions.
By killing the session and restarting with a fresh context for every atomic task, you keep the agent sharp.
What is the Ralph Loop?
The Ralph Loop is not a complex framework; it's a simple bash while loop that runs an AI coding CLI like Claude Code or Amp. Coined by Geoffrey Huntley, the name refers to the Simpsons character Ralph Wiggum—the kid who fails constantly but keeps trying until he eventually succeeds. The loop treats failure as expected, not exceptional, forcing the agent to iterate until it meets binary success criteria.
Technically, the Anthropic plugin uses a stop hook to intercept the exit when the AI tries to end a session. But a "true" Ralph Loop runs outside the agent. It kills the process entirely and restarts it to guarantee a 100% clean context. This is the opposite of vibe coding, where you accept suggestions without scrutiny. In a Ralph Loop the agent—not the human—chooses the next task from a structured requirements file, explores the code, and implements changes until the "Completion Promise" sigil appears.
Why does looping work?
AI agents have a hidden execution budget. Once the model feels it has done a "reasonable" amount of work, it wraps up and exits based on how the code looks rather than how it works. You'll often find half-implemented APIs or skipped edge cases because the model decided it was "good enough."
Worse, context windows are just arrays. Every message adds to that array until the model starts "compaction"—summarizing previous history to save space. Because that compaction loses the original project instructions, long sessions degrade their own reasoning the longer they run. Looping fixes this by starting each task with a fresh context. The agent stays focused because it isn't carrying the baggage of previous failed attempts or bloated history.
Anatomy of a Ralph Loop
A working loop relies on state files to carry memory between context resets. Don't write the prd.json yourself; humans are bad at writing binary, testable requirements. Instead, "mould the clay" by talking the spec through with the AI, then ask it to generate the structured JSON.
- prd.json: The living TODO list with binary
passes: false/trueflags. - progress.txt: Short-term memory of decisions, blockers, and files changed.
- agents.md: Long-term, project-wide patterns and conventions.
- The PIN System: A Markdown lookup table linking specific features to filenames. It stops the agent from hallucinating directory structures or inventing file names.
- The Completion Promise: A specific sigil (e.g.
<promise>COMPLETE</promise>) the agent emits only when everyprd.jsonitem passes.
A minimal prd.json looks like this:
{
"requirements": [
{
"task": "Add users table migration",
"passes": true
},
{
"task": "Implement signup endpoint",
"passes": false
}
]
}