Ralph Wiggum loops with Codex: run iterative agent passes until done

Ralph Wiggum loops with Codex: run iterative agent passes until done

~ 5 min read

#ai #automation #productivity #tools

If you have been using Claude Code recently, you have probably seen people talk about the Ralph Wiggum recursive loop pattern.

This covers how to run the same idea with OpenAI Codex.

What the Ralph Wiggum loop is

In short, a Ralph loop is an agent run pattern where you repeatedly re-invoke the agent against the same task state until it either:

  • finishes (DONE)
  • gets blocked (BLOCKED)
  • reaches a max iteration limit

Digging a bit deeper

The official Claude Code Ralph Wiggum plugin describes it as putting a subagent in a recursive Bash loop on a task. The value is not a single giant prompt; the value is the repeated execution cycle.

  • Definition: A bash script loop (while :; do…) that repeatedly feeds an AI agent (like Claude Code) a prompt, ignoring errors, until the goal is achieved.
  • Philosophy: It is “ignorant, persistent, and optimistic”, named after the Simpsons character because it keeps trying until success.
  • Core Principle: It avoids “context rot” (AI getting dumber the longer a session runs) by restarting the session every cycle and using Git as the memory.

Claude Code origin, Codex adaptation

Ralph Wiggum became popular in Claude Code workflows. Codex does not need the same plugin to achieve the same execution model.

But you can reproduce a similar pattern with codex exec in a bounded shell loop.

NOTE: codex is excellent at looping internally and long runs now, so unlike claude it can do more passes than MAX_ITERS, purely because it will often handle multiple small passes updating state before exiting; the MAX_ITERS still caps the total number of command initiations, but not necessarily the number of passes at a task.

Codex Ralph loop script

Create scripts/ralph-loop.sh:

#!/usr/bin/env bash
set -euo pipefail

STATE_DIR="${2:-./ralph}"
TASK_FILE="${1:-$STATE_DIR/TASK.md}"
MAX_ITERS="${MAX_ITERS:-20}"

mkdir -p "$STATE_DIR"
[[ -f "$TASK_FILE" ]] || {
    echo "Missing task file: $TASK_FILE" >&2
    exit 1
}

touch "$STATE_DIR/NOTES.md"
: > "$STATE_DIR/RUN_LOG.md"
rm -f "$STATE_DIR/DONE" "$STATE_DIR/BLOCKED"

for ((i = 1; i <= MAX_ITERS; i++)); do
    printf "\n## Iteration %d (%s)\n" "$i" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >>"$STATE_DIR/RUN_LOG.md"

    codex -a never exec -C "$(pwd)" -s workspace-write "
You are running one Ralph loop iteration.

Read:
- $TASK_FILE
- $STATE_DIR/NOTES.md

Do exactly one smallest useful step toward completion.
Append what you changed and why to $STATE_DIR/NOTES.md.

If complete, create $STATE_DIR/DONE with a concise summary.
If blocked, create $STATE_DIR/BLOCKED with blocker details and required input.

Before stopping, run only the smallest relevant verification command.
" 2>&1 | tee -a "$STATE_DIR/RUN_LOG.md"

    if [[ -f "$STATE_DIR/DONE" ]]; then
        echo "Done in $i iteration(s)."
        exit 0
    fi

    if [[ -f "$STATE_DIR/BLOCKED" ]]; then
        echo "Blocked at iteration $i."
        exit 2
    fi
done

echo "Hit MAX_ITERS=$MAX_ITERS without DONE/BLOCKED."
exit 3

Make it executable:

chmod +x scripts/ralph-loop.sh

Minimal task file format

Create ralph/TASK.md:

# Goal

Fix flaky Cypress test on /search route.

# Constraints

- Only edit test files and the related component.
- Do not change production behaviour outside this bug.

# Done when

- Failing test is stable for 3 consecutive runs.
- npm run lint passes.

Then run:

MAX_ITERS=12 ./scripts/ralph-loop.sh

Guardrails that matter

Ralph loops are powerful, but they can run away if unbounded.

Always define:

  • max iterations
  • writable scope
  • explicit done conditions
  • explicit blocked conditions

If you skip those four, you get drift instead of progress.

Practical improvements

After the basic loop works, add:

  1. git diff --stat snapshot after each iteration
  2. targeted test command in the task file
  3. final full validation (npm run test, npm run lint, npm run build) before merge

This keeps the rapid loop, but still enforces production-grade checks before shipping.

When to use Ralph loops in Codex

Use this pattern when work is:

  • multistep but deterministic
  • bounded to a known repo area
  • easy to validate with commands

Do not use it for open-ended design exploration where success criteria are unclear.

The key idea is straightforward: keep each agent pass small, persist state in files, and loop until there is objective evidence of done.

Is OpenClaw a fancy version of a Ralph loop?

OpenClaw represents the next step in agentic workflows (like Clancy Wiggum or R-based loops), which take the basic, “ignorant” Ralph Wiggum principle of persistent iteration and make it more structured, autonomous, and complex.

  • Autonomous Agent/Multi-Agent: OpenClaw is an autonomous AI agent, often described as an “agentic workflow” that goes beyond a simple, one-line bash script.
  • Self-Reinforcing Loop: OpenClaw uses a “heartbeat” mechanism where agents wake up, scrape recent posts, and act on them, creating a self-reinforcing dialogue.
  • More Complex Behaviour: While a standard Ralph loop might just write a script, OpenClaw creates “recursive loops” where agents validate each other’s hallucinations, sometimes leading to self-generating, weird, or “creepy” behaviours (like creating “Crustafarian” crab cults).
  • Trendiness: OpenClaw is seen as a more modern, “trendy” evolution of the core, “brute force” Ralph Wiggum methodology.

In my opinion, OpenClaw represents a significant advancement in the Ralph Wiggum loop pattern, offering a more structured and autonomous approach to repetitive tasks. It’s a testament to the power of AI in automating complex workflows and enhancing productivity.

However, it’s important to note that while OpenClaw offers many benefits, it also comes with potential risks, around security and cost that need to be carefully managed.

Both Anthropic and OpenAI continue to push the boundaries of how long an agent (and its subagents) can work without intervention and maintain a good outcome, so in many ways having to scaffold your own loop may only be required for a short while. Take a look at Model Evaluation & Threat Research (METR) to see that task length progress.

I’m also certain many of the concepts beyond long working will be adopted by them from OpenClaw. Agent Skills have also been a great way to extend core agent functionality and provide a more flexible and adaptable approach to repetitive tasks.

References

all posts →