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.
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.
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
doneSafe Ralph Loop spec
| Field | Safe version |
|---|---|
| Durable state | TASK.md, STATE.md, test logs, issue comments, or PR checklist |
| Workspace | Disposable branch, worktree, VM, or sandbox |
| Verifier | Tests, lint, browser check, CI status, or explicit acceptance checklist |
| Budget | Turn/time/token/retry cap before stopping |
| Stop condition | Verifier passes, blocker appears, no progress, budget exhausted, or approval required |
| Human gate | Merge, deploy, publish, delete, send, account, legal, financial, and reputation actions |
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.
QuestionsFAQ
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.