The Ralph Wiggum Loop, Explained

The Ralph Wiggum loop is the dumbest agent architecture that actually works: run the same prompt against your repo in a while true, forever, with fresh context every iteration. No orchestration framework, no agent graph, no memory store. A bash loop and a markdown file.

It was named and popularized by Geoffrey Huntley (ghuntley.com/ralph), who used it to brute-force entire codebases into existence. The name is the point — like Ralph from The Simpsons, the loop is not clever, has no plan, and keeps going anyway. This guide explains how it works, why it works, when it fails, and how to run one without letting it eat your repo.

The whole thing

while :; do
  claude -p "$(cat prompt.md)" --dangerously-skip-permissions
done

That's it. That is the entire architecture. Everything interesting lives in prompt.md and in the files the agent reads and writes between iterations.

Why fresh context beats a long conversation

Your instinct says a long-running session should be smarter — it remembers what it tried. In practice, long agent sessions degrade: the context fills with stale diffs, dead ends, and its own earlier mistakes, and quality slides.

Ralph inverts this. Every iteration starts clean. The agent knows nothing except:

1. The prompt (prompt.md — same every time) 2. The repo state (whatever previous iterations committed) 3. Whatever files the prompt tells it to read first

State lives in the repo, not in the conversation. A backlog file tracks what's done. A guardrails file accumulates hard-won lessons. Git history is the memory. Each iteration picks one item, does it, commits, and dies. The next iteration is born knowing only what got written down.

This is why Ralph loops scale to overnight runs where a single session would collapse: the loop can run 200 iterations and iteration 200 is exactly as sharp as iteration 1.

Anatomy of prompt.md

A working Ralph prompt has four sections. Here's a condensed real-world shape:

# Task
Read BACKLOG.md. Pick the FIRST unchecked item. Implement it completely.

Rules - Read GUARDRAILS.md before doing anything. Follow every rule in it. - ONE item per run. Do not start a second item. - All tests must pass before you commit: `npm test` - Commit with message "ralph: <item>". Check the item off in BACKLOG.md.

When you get stuck - If blocked, write the blocker under the item in BACKLOG.md and stop.

Before you exit - Append anything you learned the hard way to GUARDRAILS.md (a gotcha, a convention, a command that doesn't work here). ```

The two files it references do the heavy lifting:

BACKLOG.md — the work queue. A checklist of small, independent items. The loop's exit condition is "no unchecked items remain."
GUARDRAILS.md — the learning file. This is the trick that separates a Ralph loop that converges from one that makes the same mistake 40 times.

The guardrails file: Ralph's only memory

Because every iteration has amnesia, mistakes repeat by default. Iteration 12 rediscovers that the test suite needs DATABASE_URL set. Iteration 13 rediscovers it again.

The fix: every iteration ends by appending lessons to GUARDRAILS.md, and every iteration begins by reading it. Signal compounds:

# GUARDRAILS.md
- Tests need `DATABASE_URL=postgres://localhost:5432/test` exported.
- Do NOT touch src/billing/ — human review required.
- `npm run lint -- --fix` breaks the generated files in src/gen/. Never run it there.
- The e2e suite is flaky on first run after migration; run migrations first.

The loop teaches itself the rules of your repo, one failure at a time — and never fails the same way twice. See [ralph-guardrails-learning](/loops/ralph-guardrails-learning) in the directory for a ready-to-run version of this pattern.

What Ralph is good at

Ralph shines when the work is a queue of small, verifiable, independent items:

Burning down a PRD, feature by feature — [ralph-prd-backlog](/loops/ralph-prd-backlog)
Adding test coverage file-by-file — [ralph-test-backlog](/loops/ralph-test-backlog)
Mechanical refactors across a codebase — [ralph-refactor-backlog](/loops/ralph-refactor-backlog)
Docs that trail the code — [ralph-docs-backlog](/loops/ralph-docs-backlog)
A bug list nobody wants — [ralph-bug-backlog](/loops/ralph-bug-backlog)

Common thread: each item fits in one context window, each item has a mechanical check (tests pass, types compile), and no item depends on the loop "remembering" another.

Browse everything Ralph-shaped at [/type/ralph](/type/ralph).

Where Ralph fails

Be honest about the failure modes before you run one overnight:

Architectural work. Ralph has no plan across iterations. Ask it to "redesign the data layer" and you'll get 30 commits pulling in 30 directions. Design first; give Ralph the resulting task list.
Vague backlog items. "Improve error handling" produces an infinite loop of plausible churn. Items must be checkable.
Reward hacking. With --dangerously-skip-permissions and a "make tests pass" instruction, deleting the test is a valid move unless you forbid it. Put the prohibition in GUARDRAILS.md *and* verify test count in an evaluator.
No budget. A raw while : runs until your API bill stops it. Cap it: for i in $(seq 1 50); do ... done, plus a wall-clock timeout.

A safer Ralph

The production version adds a budget, isolation, and a completion check:

git worktree add ../ralph-run && cd ../ralph-run
for i in $(seq 1 50); do
  claude -p "$(cat prompt.md)" --dangerously-skip-permissions
  grep -q "\- \[ \]" BACKLOG.md || break   # exit when backlog is empty
done

Run it in a worktree so a bad night costs you nothing. Review the commits in the morning like you'd review a junior's PR stack — because that's what it is. If you want the loop to email you when the backlog hits empty (or when it stalls), ConnectMyEmail gives your agent an email channel without you writing SMTP glue at midnight.

Roll your own

Start with a backlog of 5–10 genuinely small items, a guardrails file with your repo's known gotchas pre-seeded, and a 20-iteration cap. The [loop builder](/builder) will generate the prompt.md, the harness script, and the safety rails for you — pick the Ralph template and fill in your backlog.

The Ralph Wiggum Loop, Explained