The Ralph loop: origin, mechanics, variants, and limits

Strip away the memes and a Ralph loop is among the smallest useful programs ever written: a shell loop that restarts a coding agent in the same repository, with the same standing prompt file, until a human interrupts it. The phrases people arrive under — "ralph loop", "ralph wiggum loop", "what is ralph loop", "ralph wiggum technique", "ralph mode", "codex ralph loop", "opencode ralph loop" — all point at that one referent, coined in a single 2025 essay and spread faster than documentation kept up. This page is the consolidated technical account: where the technique came from, what the vocabulary means, what each pass through the loop actually does, which variants now exist, and where the people who ran it longest say it breaks.

Every public claim below was checked against its linked source on 2026-08-28 — chiefly Geoffrey Huntley's origin essay and Dex Horthy's practitioner history — and every claim about YYLO's Ralph-adjacent surfaces against the committed CLI source and README. Quotes are verbatim, punctuation included. The date is part of the evidence: this technique spread through social posts faster than through documentation, so undated Ralph advice is usually secondhand folklore by the time it reaches you.

Where the technique came from

Geoffrey Huntley published Ralph Wiggum as a "software engineer" on 14 July 2025. The name is a joke taken seriously — Ralph Wiggum is the Simpsons character, and the essay keeps the bit deadpan: when the loop goes wrong, "It's Ralph Wiggum, after all." The definition is two sentences long: "Ralph is a technique. In its purest form, Ralph is a Bash loop."

while :; do cat PROMPT.md | claude-code ; done

That is the entire original implementation. cat streams a standing prompt file into the coding agent; the agent runs to completion; the loop restarts it as a fresh process with the same prompt, indefinitely. The proof project was CURSED, an esoteric programming language the loop built largely without that language existing in any model's training data. A practitioner chronology records the project being rewritten "Once in C, once in rust, and then finally in zig", ending with "It has a standard library and a stage-2 compiler (cursed lang compiler written in cursed lang)." Huntley also reported the economics that made the technique famous — a "$50k USD" contract "delivered, MVP, tested + reviewed with @ampcode." for "$297 USD" of spend. One self-reported anecdote, not a benchmark; cite it exactly that carefully.

Adoption was fast and messy. The technique "went viral in the final weeks of 2025", a team at a hackathon reported that they "put a coding agent in a while loop and it shipped 6 repos overnight", and by December 2025 a practitioner history records that "the anthropic team released an official ralph wiggum plugin". A five-line shell joke became product surface in other companies' harnesses within six months.

The vocabulary, in one place

Ralph terminology is small but unstable, because most of it spread through posts rather than docs. One pass through the words prevents most confusion:

• Ralph loop, ralph, ralphing, ralph mode, the Ralph Wiggum technique. One referent: the loop. Capitalization and suffix vary by author; nothing deeper hides behind the variation.
• The prompt file (`PROMPT.md`). The standing prompt the loop re-reads every pass. It is not composed once and frozen — the origin essay is blunt that "There is no such thing as a perfect prompt", and that the file evolves by tuning against observed behavior, not by upfront design.
• The plan file (`fix_plan.md`, or the TODO list). The prioritized remainder the agent itself maintains and works down. The originator's operating posture toward it: "The TODO list is what I'm watching like a hawk. And I throw it out often."
• Specs. A folder of declarative specifications, one file per capability, written before the loop runs. Specs are the steering surface: wrong code patterns point at the standard library; the wrong product points back at the specifications.
• Signs. Guardrail lines added to the prompt after observing a specific failure. The name comes from the essay's playground metaphor — "one then tunes Ralph by adding a sign next to the slide saying “SLIDE DOWN, DON’T JUMP, LOOK AROUND,”" — and like playground signage, signs only work while the agent still reads them.
• Doneness. The origin essay's own scale: "Ralph has three states. Under baked, baked, or baked with unspecified latent behaviours (which are sometimes quite nice!)". Practitioners interrupt the loop when the work looks baked, accepting that unspecified latent behavior rides along.

Mechanics: what one pass actually does

Each pass is a complete agent session with a fresh context window, and the technique is mostly about spending that window deliberately:

• Re-derive position from files, not memory. Every pass re-reads the same prompt, plan, and specs; nothing carries over conversationally. That is why plan-file hygiene outranks prompt brilliance — "The name of the game is that you only have approximately 170k of context window to work with."
• One item per pass. The core discipline is stated twice in the source on purpose: "One item per loop. I need to repeat myself here—one item per loop." The agent chooses which remaining item matters most itself, which the essay frames as the technique's most trust-demanding move: "you also need to trust Ralph to decide what's the most important thing to implement".
• Monolith, not mesh. "Ralph is monolithic. Ralph works autonomously in a single repository as a single process that performs one task per loop." Multi-agent choreography is explicitly deferred in the original — one repo, one process, one item.
• The primary window is a scheduler. Expensive reading and summarizing are delegated: "Your primary context window should operate as a scheduler, scheduling other subagents to perform expensive allocation-type work, such as summarising whether your test suite worked."
• Backpressure decides correctness. Generation is assumed cheap and wrong until rejected: "Anything can be wired in as back pressure to reject invalid code generation." Tests, builds, and type checkers inside the pass are the gate, and they must be fast, because the loop's value is passes per day.
• Loop the agent back onto its own output. "You want to program in ways where Ralph can loop himself back into the LLM for evaluation." Add logging, compile and inspect intermediate representations, and convert every artifact into next pass's evidence.
• Self-improvement with git discipline. "If Ralph discovers a learning, permit him to self-improve:" — the AGENT.md file records how to build and run the project and is updated by the agent itself, while the prompt orders commit, push, and tag whenever tests go green, so history accumulates one increment per pass.

The variant family

The original portability claim is one sentence: "Ralph can be done with any tool that does not cap tool calls and usage." The variants that followed prove it in both directions:

• The original bash loop. The form above, Claude Code reading PROMPT.md from stdin.
• Tool-substituted loops. Swap the agent binary and the loop is unchanged. The practitioner history records the July 2025 post's structure as while :; do cat PROMPT.md | npx --yes @sourcegraph/amp ; done — same loop, Sourcegraph's Amp inside. This is also why harness-specific spellings like "codex ralph loop" or "opencode ralph loop" name the same technique with a different inner agent.
• The Anthropic plugin. In December 2025 Anthropic shipped an official "ralph wiggum" plugin that moves the loop inside the harness as a stop hook instead of a shell around it. The field report is candid: "It dies in cryptic ways unless you have --dangerously-skip-permissions", it installs hooks in places that are hard to find, and — the substantive critique — it optimizes for running forever when the point of the technique is to "carve off small bits of work into independent context windows".
• Scheduled variants. Teams aiming the technique at existing codebases tend to stop running it interactively and schedule it overnight, because "Waking up to one small refactor every morning is better than both a) waking up to none and b) waking up to 50."
• Bounded variants. YYLO's committed reinterpretation keeps the name and removes the forever: its skill installer provisions ralph-loop into the skill directory of every supported harness — Claude reads it from .claude/skills/, Codex from .agents/skills/, and Pi from .pi/skills/ — and the skill's contract is "Execute exactly one explicitly assigned Kanban task to a validated queued commit. Use only when the user explicitly requests ralph-loop." The README example runs it with a one-iteration cap (ypl '/skill:ralph-loop' -i 1), yylo loop -n 5 bounds outer command workflows while -i bounds iterations inside an agent invocation, and the committed config defaults agent runs to a single iteration unless explicitly raised. The loop ends by design; the bounded-loop guide owns that practice.

One more variant-family warning belongs here rather than anywhere else: the term is diluting as it spreads, and the history signs off with it — "Hurry up before it gets semantically diffused." When a vendor says "Ralph", check which of the above they mean before copying their config.

Hard limits, from the people who ran it

The limits below are not adversarial criticism; nearly all are quoted from the technique's originator or its longest-running practitioner.

• Greenfield first, existing codebases reluctantly. The originator's own boundary: "There's no way in heck would I use Ralph in an existing code base" — "This works best as a technique for bootstrapping Greenfield, with the expectation you'll get 90% done with it." Practitioners who aimed it at an existing frontend anyway report the seam: the loop ran a large standards refactor, claimed to be finished after six hours, and the PR still gathered merge conflicts; the recorded lesson is that re-running the loop on fresh code beats rebasing a stale one, in small scheduled increments.
• Nondeterminism is the structural weakness. The failure surface is search: the agent greps, concludes the code is missing, and reimplements what already exists. "This nondeterminism is the Achilles' heel of Ralph." The originator's mitigation is a sign — "don't assume it's not implemented" — and the residual risk stays after the sign is up.
• You will wake up to a broken tree. The essay says it plainly: "Yep, it's true, you'll wake up to a broken codebase that doesn't compile from time to time, and you'll have situations where Ralph can't fix it himself." The operator's morning decision is git reset --hard versus a rescue prompt series — a judgment call, every time.
• State lives in markdown the model itself edits. The loop remembers through plan files and TODO lists, which is exactly the fragile surface: the same non-deterministic process that fails also owns the record. YYLO's committed README names this failure class "Fragile state" in its own Ralph assessment; the durable-state answer this site teaches is task truth in the ledger, where the record is not model-editable prose.
• The only stop condition is you. Overbake and you get "all sorts of bizarre emergent behavior, like post-quantum cryptography support" — capability nobody asked for. And for exploratory work the practitioner verdict is that "you probably don't want ralph in the first place". A loop with no stop semantics needs an operator who supplies them; bounded failure design is the discipline that makes long-running loops safe to leave.
• Senior attention is a precondition, not a leftover. The essay closes on this: "engineers are still needed. There is no way this is possible without senior expertise guiding Ralph. Anyone claiming that engineers are no longer required and a tool can do 100% of the work without an engineer is peddling horseshit." Watching the stream, diagnosing the bad pattern, writing the next sign — that is the engineering.

What this technique is for

Taken whole, the honest summary is the originator's own oxymoron: "the technique is deterministically bad in an undeterministic world." A Ralph loop reliably produces passes that are individually unreliable, and it earns its keep exactly when bulk generation on a greenfield target with a spec stack is worth that trade and a senior engineer is present to tune the signs. Two operating notes travel with any variant: the prompt file is a standing injection surface the loop re-reads every pass, so whoever can write PROMPT.md steers every iteration — treat it with the boundaries the prompt-safety guide sets — and any loop you cannot afford to leave unattended needs explicit bounds rather than a faster interrupt reflex.

This page is maintained as the citable record of the technique — origin, vocabulary, mechanics, variants, and limits, each claim linked and dated 2026-08-28. If the account saves you a re-derivation, cite this URL rather than pasting the text: the technique's own short history is the argument for attribution, because uncredited copies are already drifting from what the originator actually wrote.