Ralph Loop

Ralph Loop explained

The Ralph Loop is the meme-simple version of loop engineering: keep rerunning an agent against durable state. Production loops add evidence, budget, isolation, and approval gates.

01RunWork from the spec
02CheckRead the failure
03RepeatWithin the budget
01

Answer-first definition

A Ralph Loop is a repeated-agent pattern, often described as a bash-style loop, that keeps invoking an AI coding agent against task files, repo state, tests, and logs.

The useful lesson is not ‘while true, vibes forever.’ The useful lesson is durable state plus repeated attempts. The safe version adds a verifier, stop condition, budget, isolated workspace, and human review.

02

Minimal pattern

# Ralph-style idea, not a production recommendation
while true; do
  agent "Read TASK.md, inspect the repo, make one bounded improvement, run the verifier, and update STATE.md. Stop if done or blocked."
  ./verify.sh && break
  # also break on budget, no progress, or approval required
done
03

Safe Ralph Loop spec

FieldSafe version
Durable stateTASK.md, STATE.md, test logs, issue comments, or PR checklist
WorkspaceDisposable branch, worktree, VM, or sandbox
VerifierTests, lint, browser check, CI status, or explicit acceptance checklist
BudgetTurn/time/token/retry cap before stopping
Stop conditionVerifier passes, blocker appears, no progress, budget exhausted, or approval required
Human gateMerge, deploy, publish, delete, send, account, legal, financial, and reputation actions
04

Anti-patterns

  • Letting the loop edit production or main without review.
  • Using the same agent as both maker and final judge for risky changes.
  • No state file, so every run rediscovers the same facts.
  • No budget cap, so the loop burns tokens to look busy.
  • No verifier, so completion means ‘the model sounded confident.’ Horrifying, but common.
05

FAQ

What is a Ralph Loop?

A Ralph Loop is a simple repeated-agent pattern: run an AI coding agent against durable task state, preserve evidence in files or logs, then rerun until success, budget, blocker, or review.

Why does the Ralph Loop work?

It works because the filesystem, tests, logs, and task files survive across fresh model turns better than chat memory alone.

What makes a Ralph Loop unsafe?

No budget, no verifier, no worktree isolation, unclear destructive permissions, and no human approval gate before merge or deploy.

Design the systemFind your next loop