Ralph Loop

The Ralph Loop (also ‘Ralph Wiggum Loop’) is a harness pattern for forcing an agent to continue long-horizon work past the point where it would otherwise stop.

Ralph Loop

The Ralph Loop (also “Ralph Wiggum Loop”) is a harness pattern for forcing an agent to continue long-horizon work past the point where it would otherwise stop.

Named reference: https://ghuntley.com/loop/

The Problem

Models tend toward early stopping. When a context window fills up or a task seems “done enough,” the agent exits. For long tasks that span multiple context windows, this means incomplete work without a mechanism to continue.

The Pattern

The harness intercepts the agent’s exit signal via a hook. Instead of allowing the exit, it:

1. Clears or compacts the current context window
2. Reinjects the original goal/prompt into the fresh context
3. The agent reads current state from the filesystem (durable across iterations)
4. Continues working toward completion

Each iteration starts with a clean context but full access to accumulated work on the filesystem. The agent doesn’t need to “remember” prior steps — it reads them.

loop:
  [fresh context] ← reinjected original prompt
  [filesystem] ← durable state from all prior iterations
  agent works → updates filesystem
  if exit signal detected → intercept → loop again
  if completion condition met → allow exit

Why It Works

The filesystem is the memory. Clean context means no context rot, no accumulated noise, no degraded reasoning from a full window. The agent reconstructs where it is from durable artifacts, then continues.

This is the same reason autoresearch runs 5-minute bounded experiments in a loop rather than one long run — each iteration is self-contained and comparable; state persists in train.py modifications.

Canonical Loop Architecture (PRD → JSON → Single Task)

The pattern that emerged across independent implementations (Ralph, Anthropic’s demo, coding agents):

1. Generate requirements document (PRD) — full scope of the work
2. Decompose into structured task list (JSON file on filesystem)
3. Loop:
   a. Select one task from the list
   b. Start fresh context: re-inject prompt + read current filesystem state
   c. Implement, test, and document that task
   d. Mark complete in the task file
4. Repeat until task list exhausted

Key design rule: one task per iteration. Selecting only one task per fresh context prevents the agent from context-poisoning itself by trying to track multiple in-flight changes across a long context.

Both Ralph and Anthropic’s minimal harness demo are noted for their small repository size — the architecture is simple, the complexity was solved at the pattern level.

In Practice (OpenAI Codex case study)

The full development loop is a Ralph Loop variant:

1. Engineer writes prompt → Codex opens a PR
2. Codex reviews its own changes, requests agent reviews, responds to feedback
3. Iterates until all agent reviewers pass
4. Agent handles build failures, re-runs, and retries automatically
5. Escalates to human only when judgment is required
6. Merges

Single runs regularly run 6+ hours unattended while engineers sleep.

Completion Conditions

The harness must define what “done” means, or the loop never exits. Common approaches:

• All automated tests pass
• No agent reviewer has outstanding objections
• A specific artifact is produced (PR opened, plan marked complete)
• Metric threshold reached (e.g., val_bpb improvement for autoresearch)

Without a clear completion signal, the loop becomes an infinite loop or terminates on a timeout.

Related Pages

• Agent Harness — harness component model; Ralph Loop as one primitive
• Autoresearch Karpathy — the 5-min experiment loop as a bounded Ralph Loop analog