AI: The Ralph Loop

"Ralph Loop" (or Ralph Wiggum Loop) is an architectural pattern where an AI coding agent is wrapped in an infinite while loop to execute tasks autonomously over long periods.  

How a "Ralph Loop" Works

1. Task: You feed the loop a structured backlog, like a local Product Requirements Document (prd.json) or a checklist.
2. Fresh Instance: The loop spawns a brand-new AI agent session (using tools like Claude Code or Gemini CLI) with a clean context window.
3. Execution & Memory: The agent reads the checklist, picks the highest-priority task, edits the code, and runs your compiler, linter, or test suite.
4. Stop Hook Intercept: When the AI attempts to exit, a custom script or hook intercepts it and verifies if the code compiled and if tests passed.
5. Next Iteration: If the task failed, the script launches a fresh agent instance. Because the previous agent modified files and left notes on disk, the new agent picks up right where the last one left off. The loop only terminates when all tasks pass.

Architectural Problem It Solves

1. Context Window Amnesia: In long programming sessions, an LLM’s context window fills up with thousands of lines of chat history. This "dilutes" its attention, leading to hallucinations, laziness, and bad code.
2. State in Files, Not Chat: By restarting the agent on every iteration, context remains tiny and hyper-focused. The "memory" of the application doesn't live in the AI’s chat history; it lives in your actual Git history, codebase changes, and local text files. 

Guardrails

A Ralph Loop will spin endlessly and drain your API wallet unless it is bound by rigid architectural guardrails: 

1. Honest Outcome Signals: The loop requires a fully automated testing suite, type-checker, or CI pipeline. If the AI cannot programmatically test its own code, it will hill-climb in the wrong direction.
2. Iteration Limits: Architectures must set hard budget caps (e.g., max 35 loops) to stop an agent from getting stuck on a bug and burning hundreds of dollars in API tokens

Afterwards

You need to stop after X iterations and have separate system do an adversarial review of the written code.