Ralph Wiggum loop

January 21, 2026 • 7 min read • #AI, #coding, #claude code, #llm, #codex

If you’ve been watching AI-assisted coding lately, you’ve probably seen people obsessing over the “Ralph Wiggum technique”: a deliberately simple pattern where you keep re-running the same instruction until the agent has worked through all the TODOs and can prove it’s done.

The name is a joke (Ralph from The Simpsons is famous for bumbling persistence), but the idea is serious: turn a flaky one-shot agent into an iterative system where failures become “just another iteration.”

The original: “Ralph is a Bash loop”

Geoffrey Huntley’s original framing is: Ralph is not a product, it’s a technique, and in its purest form, it’s literally a shell loop.

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

The important bits aren’t the syntax, it’s what the loop means:

You write a PROMPT.md that contains the task, constraints, and usually a checklist/TODO list.
The agent runs, edits files, runs commands/tests, updates TODOs, etc.
If it’s not done, you run it again—same prompt again—until completion.

Huntley emphasizes that this style of building requires “faith” and “eventual consistency”: you steer by improving the prompt and guardrails (“add signs next to the slide”), rather than micromanaging each step.

What makes it work: disk as memory, loops as reliability

The “Ralph” worldview is:

LLMs are stochastic: one run may miss a detail, forget a constraint, or stop early.
But iteration is cheap: running again is often enough to correct course.
State lives in the repo: files, tests, git history, logs—not in the agent’s short-term context.

That’s why Ralph-style prompts usually include:

Clear success criteria (tests passing, lints clean, acceptance checks met).
A completion signal (“print DONE when finished”) so the loop can stop safely.

The Claude Code plugin flavor: stop-hook loops (ralph-loop)

The official Claude Code plugin approach packages this technique into a “self-referential” loop using a Stop hook.

At a high level:

The plugin persists the original prompt (e.g., .claude/ralph-loop.local.md)
Claude works normally, editing files and accumulating changes
When Claude tries to exit, the Stop hook intercepts the exit and re-submits the same prompt
The loop ends when the completion criteria is met (completion phrase found) or a max-iteration limit is reached

One key nuance: this plugin re-feeds the prompt within the same session, unlike an external bash loop that often restarts the tool fresh each run.

That difference matters in practice:

Same-session looping can accumulate context clutter (good: continuity; bad: drift).
Fresh-session looping can enforce context reset (good: less drift; bad: less continuity).

A more “productionized” custom implementation: ralph-orchestrator

If you like the technique but want more guardrails, ralph-orchestrator is an “improved implementation” with practical controls: spend limits, retries/circuit breakers, monitoring/metrics, security controls, and git checkpointing.

It also introduces two orchestration modes:

Traditional: the original “simple loop until done”
Hat-based: structured multi-role workflows (reviewer/tester/documenter personas coordinating through events)

Think of it as “Ralph, but with seatbelts.”

The simplest implementation to try: ralphy

ralphy demo

If what you want is minimum ceremony, ralphy is exactly that: a single bash-driven workflow that runs an agent “until done,” either from a one-liner task or a PRD/todo list.

From its README, it supports:

Single task mode (./ralphy.sh "add dark mode")
Task-list/PRD mode (./ralphy.sh --prd PRD.md)
Optional project rules/config (.ralphy/config.yaml)
Multiple “engines” (Claude Code by default, plus others via flags)

Even though it has plenty of options, the experience is still “one script, run the loop.”

When Ralph loops are great

Ralph shines when the work has objective feedback and can be chipped away iteratively:

Greenfield scaffolding: generate an initial service/app with structure, docs, and tests.
Tasks with tight success criteria: “all tests pass,” “lint clean,” “API endpoints match spec.”
Refactors with guardrails: repeated small changes + running tests each iteration.
Backlog grinding: a PRD or checkbox list where the agent can work item-by-item.
“Overnight builds”: you’re okay letting it run for a while and reviewing the result later.

When Ralph loops are not great

Ralph is a terrible fit when “done” is fuzzy or risky:

Ambiguous product/design decisions: the loop will thrash because there’s no crisp win condition.
High-stakes production debugging: you usually want targeted diagnosis, not blind iteration.
Tasks requiring external approvals (security, legal, stakeholder sign-off): the loop can’t unblock itself.
Environments without reliable verification: if tests don’t exist (or are flaky), the loop can “declare victory” incorrectly.
Cost / safety-sensitive contexts: infinite-ish loops can burn tokens, time, or make risky changes unless you set strict limits.

Practical guardrails

If you try this technique, the biggest quality jump comes from adding a few hard constraints:

Always set max iterations (even if it’s high).
Add a completion promise that’s hard to accidentally emit.
Make the prompt include verifiable gates: run tests, lint, build, and report results.
Put “do not touch” boundaries (files/dirs) in the prompt/config.
Prefer smaller PRDs: split big work into phases so the loop doesn’t wander.

Closing thought

The “Ralph Wiggum technique” is less about clever prompting and more about turning LLM coding into an iterative process: run → observe state changes → run again → converge.

Huntley’s original version is the purest expression: a bash loop around a prompt file.
The Claude Code plugin version operationalizes it with a Stop hook that prevents the agent from exiting until completion conditions are met.
Tools like ralph-orchestrator add the “real-world” controls teams tend to want.
And ralphy is the low-friction way to get the feel of the technique fast.