Ralph Wiggum Loop

A simple outer loop restarts an agent with fresh context after each unit of work, letting a bash script do what sophisticated orchestration frameworks promise.

Understand This First

• Context Window – context exhaustion is the problem this pattern solves.
• Verification Loop – each iteration uses verification to confirm the work before exiting.
• Checkpoint – each iteration commits, creating a save point for the next.

Context

You’re directing an agent to complete a task that takes more than one session’s worth of work. Maybe it’s a multi-file refactoring, a feature that touches dozens of components, or a migration that needs to be applied incrementally. The agent can handle any single piece of the work, but the whole job exceeds what fits in one context window.

The usual solutions involve either compacting the conversation (summarizing what came before to free up space) or building an orchestration framework that manages state, routing, and subtask delegation across agents. Both work. Both also introduce complexity: compaction loses detail, and orchestration frameworks add layers of abstraction between you and the work.

There’s a third option that’s embarrassingly simple.

Problem

How do you keep an agent productive across a long task without sophisticated orchestration or degraded context?

An agent working through a multi-step plan will eventually exhaust its context window. The early stages of the conversation, where the plan was established and the first decisions were made, get pushed out by the accumulating weight of later work. The agent starts forgetting what it already tried, revisiting dead ends, or contradicting earlier decisions. Compaction helps but loses detail. Orchestration frameworks help but add infrastructure. Neither is wrong, but for many tasks, both are heavier than what the situation requires.

Forces

• Context windows are finite. Long tasks exhaust them.
• Compaction preserves continuity but discards detail. Every summarization is lossy.
• Orchestration frameworks manage state across agents but add moving parts, configuration, and debugging surface area.
• Agents are stateless across sessions. A fresh invocation has no memory of what the previous one did unless you give it one.
• Plans are durable artifacts. A checklist in a file survives across any number of agent restarts.

Solution

Write a shell loop that invokes an agent, waits for it to finish, and invokes it again. The agent reads a plan file at the start of each iteration, picks the next incomplete task, does the work, marks it done, commits, and exits. The loop restarts it with a clean context window. The plan file is the coordination mechanism; the loop is the orchestrator.

A minimal implementation looks like this:

while true; do
  claude "Read PLAN.md. Pick the next incomplete task. \
    Implement it. Mark it done. Commit your changes."
  if [ $? -ne 0 ]; then break; fi
done

That’s it. No framework, no state management, no routing logic. The plan file carries all the state the agent needs. Each iteration starts with full context budget, reads the plan, and focuses entirely on one task.

The name comes from Geoffrey Huntley, who named the pattern after Ralph Wiggum from The Simpsons for the character’s cheerful, persistent, one-thing-at-a-time energy. The agent doesn’t need to be clever about sequencing. It just needs to show up, look at the list, do the next thing, and leave.

What makes this work isn’t the loop. It’s the plan file. The plan must be:

• Concrete. Each task should be small enough for one agent session. “Refactor the authentication module” is too big. “Extract the token validation logic into a separate function and update its callers” is about right.
• Self-describing. The agent should be able to read the plan cold, with no prior context, and understand what needs doing.
• Mutable. The agent marks tasks as complete, so the next iteration knows what’s left. A checkbox list works well.
• Exit-conditioned. The agent needs to know when to stop. “All checkboxes are checked” or “all tests pass” are clear exit conditions.

The verification step matters. Before exiting each iteration, the agent should run tests, check compilation, or validate the change in whatever way is appropriate. If verification fails, the agent can retry within the same iteration. Only a verified change gets committed and handed off to the next cycle.

How It Plays Out

A developer needs to migrate forty API endpoints from Express to Hono. Each endpoint follows the same general pattern but has its own quirks in middleware, validation, and response formatting. Writing an orchestration framework for this would take longer than doing the migration by hand. Instead, the developer writes a plan file listing all forty endpoints with checkboxes, starts a Ralph Wiggum Loop, and walks away. Each iteration picks the next unchecked endpoint, migrates it, runs the endpoint’s tests, checks the box, and commits. The agent runs through the list over the next several hours, and the developer reviews the commits the next morning. Three endpoints needed manual attention where the migration wasn’t mechanical. The rest were clean.

A team uses a nightly loop to keep documentation in sync with the codebase. The plan file is regenerated each evening by a script that compares doc files to their corresponding source modules and lists discrepancies. The loop invokes an agent for each discrepancy: update the documentation, verify the links, commit. By morning, the docs match the code. No framework, no coordination between agents, no state to manage. The plan file is both the input and the progress tracker.

An engineer writes a loop that has the agent read a failing test, implement the fix, run the suite, and commit if green. The plan file is implicit: the test suite itself. Each iteration starts fresh, runs the tests, picks the first failure, and works on it. When the suite passes, the loop exits. It’s test-driven development where the developer wrote the tests and the agent writes the code, one test at a time, with no context carried between fixes.

Consequences

The Ralph Wiggum Loop trades sophistication for robustness. Every iteration gets a clean context window, so there’s no degradation over time. There’s no framework to configure, debug, or maintain. The plan file is a plain text artifact that humans can read, edit, and version-control.

The cost is redundant work. Each iteration re-reads the plan, re-orients itself, and rediscovers context that the previous iteration already had. For tasks where successive steps are tightly coupled and each one depends on detailed knowledge of what the previous step did, this overhead can be significant. Compaction or a persistent orchestration framework would be more efficient in those cases.

The pattern also assumes tasks are decomposable into independent-enough units. If step seven can’t be understood without the full context of steps one through six, restarting from scratch at step seven wastes most of the iteration on re-establishing context. The plan file can carry summaries of prior work, but there’s a limit to how much context you can pack into a plan file before it defeats the purpose of starting fresh.

Convergence isn’t guaranteed. If the plan is vague, the agent may thrash: picking the same task repeatedly, implementing it differently each time, and never marking it done. A good plan with concrete exit conditions makes convergence reliable. A bad plan makes the loop spin.

Related Patterns

• Solves: Context Window – each restart gives the agent a full context budget.
• Contrasts with: Compaction – compaction extends one session; the Ralph Wiggum Loop replaces sessions entirely.
• Uses: Checkpoint – each iteration commits, creating a rollback point.
• Uses: Verification Loop – each iteration verifies its work before exiting.
• Uses: Progress Log – the plan file serves as a progress log that persists across restarts.
• Uses: Plan Mode – the plan file is the product of plan mode, consumed by each iteration.
• Uses: Externalized State – the plan file externalizes the agent’s task state into a readable, editable artifact.
• Enables: Harness (Agentic) – a shell loop is a minimal harness.

Sources

• Geoffrey Huntley coined the term “Ralph Wiggum Loop” and published the canonical description and reference implementation (ghuntley.com/ralph/, 2025). The name references Ralph Wiggum from The Simpsons for the character’s persistent, good-natured, one-track approach.
• Block’s Goose project adopted the pattern with a dedicated tutorial, demonstrating the loop with plan-file-driven task completion and automatic git commits per iteration.
• Vercel Labs published a reference implementation showing the pattern integrated with their AI SDK, validating that a shell loop could replace framework-level orchestration for many real-world tasks.