The problem

“Ralph” is a pattern that’s been making the rounds in dev-tools circles: a one-line shell loop that feeds the same prompt to a fresh AI coding agent, permissions skipped, until the work is finished. It’s popular because it’s dumb, cheap, and reportedly gets real software built overnight. But the canonical version is a while-loop running an agent unattended with no iteration cap, no structured record of what happened each pass, and no way to check its own “done” claims — you just trust the output. That’s the same problem enterprises run into with any agent-driven automation: unattended execution is only safe if you can bound it, audit it, and refuse to take the agent’s word for “finished.”

The approach

I built ralph.py, a standalone Python script with no dependencies beyond the standard library and the Claude CLI. You hand it a goal.md with three sections — the work to do, what “done” looks like in criteria that can actually be checked against a file or a command’s output, and constraints that must hold the whole time — and it drives `claude -p` in a loop with a hard `–max-iterations` ceiling and an explicit completion string the agent has to print on its own line before the loop will stop. There’s also `–dry-run`, which composes and prints the exact prompt for iteration 1 without spending a token, so you can sanity-check the setup before committing to a run.

Every iteration gets logged twice: a structured JSON record per run (tool calls, duration, token usage in/out, exit code, whether the completion signal actually fired) that a script or dashboard could query later, and a parallel human-readable markdown trail with the full prompt and full response for every pass, append-only so nothing gets silently overwritten. Between iterations, a trimmed progress.md gets handed forward — the last N iterations’ worth of “what was done” and “open items” — so each fresh, memory-less agent instance knows what its predecessor did without re-reading the whole project from scratch.

What I learned

The loop mechanics were the easy part. The real work was writing a goal with an end state that’s actually machine-checkable — a vague “keep going until it’s good” goal either stops too early or churns forever, because a fresh-context agent has no way to judge “good enough” except what you gave it to check against. The sharper lesson came from verifying the script itself: partway through the build, the installed Claude CLI silently rejected the exact flag combination the spec called for (`–output-format stream-json` without `–verbose`). If I’d been eyeballing the output instead of running each verification step against a defined pass/fail bar and recording the real result, I’d have logged a false success. That’s the entire argument for bounding and logging this pattern instead of trusting it: agents, and the CLIs underneath them, claim things went fine more often than they actually did.

Where this could go

The pattern generalizes past coding. Any workflow where you want an agent to grind on something in short, fresh-context passes — ticket triage, data migrations, repetitive drafting, compliance sweeps — needs the same three pieces this project forces you to define up front: a verifiable end state, a hard ceiling on how long it’s allowed to run unattended, and a structured log you can query instead of a scrollback you have to read line by line. At team scale, that structured JSON log is what turns “an agent ran overnight and says it’s done” into something an engineering lead can actually audit before merging or shipping it — which is the difference between a fun demo and something you’d let touch production. The obvious next step is replacing the self-reported completion signal with a deterministic check — tests, a diff against a spec, a separate judge pass — since trusting an agent’s own “done” claim is precisely the failure mode this project exists to catch.