Ralph Loop

Definition

The Ralph Loop (also called the Ralph Wiggum technique) is an autonomous AI coding pattern where a bash loop repeatedly spawns fresh AI agent instances, feeding each the same prompt file, until all machine-verifiable completion criteria pass. Named after the perpetually-confused-but-persistent Simpsons character, it embodies the philosophy of persistent iteration despite setbacks.

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

Each iteration gets a clean 200K-token context window. Memory persists only through files on disk: git history, progress.txt (append-only learnings), and prd.json (user stories with passes: true/false status).

Key Distinction: External Verification vs. Self-Assessment

The Ralph loop’s critical innovation over conventional agent loops (ReAct, Plan-and-Execute) is external verification. Conventional agents rely on the LLM’s own self-assessment to decide when to stop. The Ralph loop intercepts exit attempts via stop hooks and checks for a literal completion-promise string. The agent is not considered finished when it believes it is done — only when external tooling (tests, typecheck, lint) confirms success.

Origins

Who	Role
Geoffrey Huntley	Created the pattern (~May 2025). “Sit on the loop, not in it.”
Matt Pocock	Popularized it (Dec 2025) with 11 tips, the skills repo, and Sandcastle library.
Ryan Carson (Snarktank)	Built the most-starred implementation (21,235 stars). Runs 3 parallel instances.

How It Works

Phase 1: Define Requirements

Human + LLM produce a PRD broken into user stories, each small enough for one context window.

Phase 2: The Ralph Loop

Each iteration:

Read prd.json and progress.txt
Pick highest-priority incomplete story
Implement the story
Validate (typecheck, lint, tests — the “backpressure”)
Commit with passing checks
Update prd.json (mark passes: true) and append learnings to progress.txt
Context cleared — next iteration starts fresh

Why It Works

Context rotation: Sessions that start with precise multi-file edits degrade into single-file tunnel vision by the 90-minute mark [S15]. Fresh context per iteration prevents this degradation curve.

Convergence through iteration: The probability of successful completion follows P(C) = 1 - (1 - p_success)^n. As n increases, probability approaches 1 [S06].

Filesystem as memory: Git history plus progress.txt carry inter-iteration context, which prevents error compounding while keeping each session lean [S01].

Bounding the Loop: Anti-Patterns and Guardrails

ASDLC.io’s pattern catalog (last updated 2026-03-18) frames the Ralph loop with a warning the earlier sources on this page did not carry: persistence is not quality. Running the loop for unbounded generation without a spec produces what Dan Cripe (as reported by ASDLC) calls “100 million lines of crappy code” — technically functional, architecturally incoherent, unmaintainable.

Contested classification. ASDLC states directly that the Ralph loop “is a persistence mechanism, not a development methodology”, and treats using it as a methodology as the root cause of the anti-pattern above. This page’s earlier position (2026-08-03, drawn from the Huntley/Pocock/Snarktank sources) described it as “the dominant autonomous coding methodology of 2026” — retained below under Implications. Both positions stand: the pattern’s adoption as the default way people run autonomous coding agents is well evidenced, while ASDLC’s narrower claim is about what the mechanism itself supplies — iteration, not architecture.

Anti-pattern	Failure mode
Vague prompts (“improve this codebase”)	Divergence; endless superficial changes
No external verification	Self-assessment trap; the agent hallucinates success
No iteration caps	Infinite loops; runaway API cost
No sandbox isolation	Agent reaches host secrets — SSH keys, cookies
No context rotation	Context rot; degraded reasoning
No progress files	Fresh iterations re-discover completed work

Documented guardrails: hard iteration caps of 20-50; forced context rotation at 60-80% of window capacity (not merely a fresh window per iteration); sandbox isolation via Docker or WSL; exact completion-promise strings to prevent token waste; a git commit every iteration to bound logic drift; per-session API cost tracking.

ASDLC further argues that default exit criteria — tests pass, compilation succeeds — verify function but never architectural coherence, and proposes pairing the loop with a constitutional-review step that checks output against architectural principles rather than functional requirements.

Implications. The loop’s exit criteria are its real design surface. A vault adopting Ralph-style ingest for llm-wiki operations inherits this exactly: wikilint: OK is a functional gate, not an architectural one — it proves a page is well-formed, never that it is well-reasoned. The bounded version of the pattern therefore needs a second, non-mechanical review step, and the table above is the concrete checklist for whether any given loop is bounded at all.

Map-Reduce: Initializer + Sub-Agents

For inherently parallel or large mechanical work, a single sequential loop becomes the bottleneck. ASDLC documents a named variant:

Initializer agent — runs the discover/define phase and writes a central plan or progress file (e.g. a list of 50 database migrations).
Sub-agents — each receives one chunk of that plan and runs its own Ralph loop inside a tightly scoped, isolated context window.
Coordination — progress merges through git history, orchestrated by a multi-agent harness or a merge queue.

The point is action-space isolation: sub-agents stay fast because their context never accumulates the whole problem, while the initializer keeps the strategic overview. Scopes can be partitioned by feature area, by file tree, or — as in Agentheim — by Domain-Driven Design bounded contexts. The partitioning principle is orthogonal to the Map-Reduce shape; DDD bounded contexts are one natural unit when a codebase already has clear subsystem boundaries.

Implications. Parallel loops do not need branch-level isolation if the plan file partitions the action space first. Mapped onto this vault, the initializer is the batch router that claims a themed set of sources and each sub-agent is a single-source ingest — close to what the synaptic-ingest batch pipeline already does by hand, with raw/.ingest-queue/ as the plan file.

Relationship to Agent Loop

agent-loop documents the abstract pattern (while True: observe -> think -> act -> update state). The Ralph loop is a concrete specialization with three engineering decisions:

External verification (stop hooks, machine-verifiable criteria) over LLM self-assessment
File-based inter-iteration memory (git + progress.txt + prd.json) over conversation history
Fresh context per iteration to prevent context rot

Inner Loop vs Outer Loop

ASDLC maps the pattern onto OODA and adds a distinction the earlier sources left implicit: the Ralph loop is an outer loop that wraps an inner prompting loop. ReAct’s Thought-Action-Observation cycle runs at the inference layer, inside one agent invocation; the Ralph loop wraps that whole cycle at the OS and repository layers. Observe becomes reading codebase state and failed builds; Orient becomes marshalling context and reading the progress file; Decide becomes planning the next iteration; Act becomes editing files, running tests, and committing.

This refines rather than reverses the framing above: external verification is still what distinguishes Ralph from a self-assessing agent loop, but ReAct is the thing Ralph wraps rather than the thing it replaces. The implementation open-ralph-wiggum makes the layering literal — with RALPH_CODEX_GOAL=1, Ralph owns cross-iteration retries while Codex’s own goal mode owns a single iteration.

Implications. Inner and outer loops are separately swappable. A team can change the inner prompting strategy without touching the harness, and change the harness without retraining anyone on the prompting pattern — which is precisely why one CLI can drive six different coding agents.

Relevance to This Vault

This vault already has a ralph-converter skill installed that converts markdown PRDs to prd.json — the exact input format the Ralph loop consumes. However, the skill is orphaned: zero wiki pages reference it, no log entry documents its use, and the source remains uncaptured.

The RonanCodes LLM Wiki implementation ronancodes-llm-wiki was itself built using Ralph loops, and its documentation proposes running ingest/lint as a Ralph-style loop: process sources one at a time, each in a fresh context, progress tracked in log.md.

Limitations

Strong fit: Greenfield implementation with clear, machine-verifiable criteria; test-driven development; mechanical refactoring with deterministic verifiers
Weak fit: Subjective quality goals (“make it look good”) have no machine-verifiable criteria; exploratory work where direction depends on intermediate discoveries [S06]

Implications

The Ralph loop is infrastructure-level tooling, not a novelty. With 194K+ installs of the official Anthropic plugin alone, plus 10+ independent implementations across Claude Code, OpenCode, Codex, Gemini CLI, and Copilot CLI, it represents the dominant autonomous coding methodology of 2026. For this vault, it provides a concrete reference point for the abstract agent-loop pattern and a proven model for running llm-wiki ingest-query-lint cycles with fresh context per source.

Open Questions

At what task complexity does the Ralph loop’s overhead (fresh context setup, commit per iteration) outweigh benefits over a single long session?
How do multi-agent variants (parallel loops on different branches) interact with a single-agent wiki ingest pattern?
Should this vault adopt Ralph-style ingest (one source per iteration, lint-verify, log-track) for its own operations?
(the multi-agent question above was partially answered 2026-08-11 by ASDLC’s Initializer + Sub-Agents variant; the part still open is whether a knowledge-ingest workload, where sources contradict each other, can be partitioned as cleanly as a code workload where they do not.)

External Links

Sources

snarktank-ralph — flagship 21,235-star implementation
open-ralph-wiggum — multi-agent CLI implementation of this pattern
agent-loop — abstract pattern the Ralph loop specializes
llm-wiki — parallel application to knowledge compilation
claude-code — the agent tool most commonly used in Ralph loops

LLM Wiki — Synaptic Lattice

Explorador