ralph

A stateless orchestrator, written in Bash, that loops a coding agent against acceptance criteria until it reports the work done.

Status: finished experiment. Built January–February 2026, not maintained. The July 2026 commit is a merge that published an existing branch — not new work.

---

What it did

ralph.sh runs a coding agent (Claude Code) repeatedly against the same prompt until the task's acceptance criteria are met. The design bet is in the word stateless: each iteration works out what remains by inspecting the actual project — files, git status, command output — rather than by carrying a memory of previous iterations. The agent ends every pass by emitting RALPH_PROGRESS (work happened, go again) or RALPH_COMPLETE (criteria met).

Around that loop, the parts that turned out to matter in practice:

• Cost tracking and budget caps — running cost per iteration, --budget to hard-stop at a dollar limit, --warn-at for a notification threshold. An unattended loop against a metered API needs a kill switch more than it needs features.
• Stuck detection — each iteration hashes the Actions: section the agent reports. Same hash N times running means it's spinning, and you get told. This is why action reporting was mandatory in the prompt format.
• Queue directives — prompts can chain work: RALPH_THEN to queue siblings, RALPH_ADD to append, RALPH_WAIT_USER to stop for a human. Directories of prompts expand recursively.
• Subagent delegation, rate-limit handling, crash recovery, live progress logging.

Roughly 20k lines in the repo, most of it the orchestrator, prompt templates and benchmarks. 96 commits, nearly all in January 2026.

Why I stopped

The loop needs its acceptance criteria defined up front. That single requirement decides what the tool is good for.

It makes ralph genuinely good at rebuilding something that already exists — you can describe "done" precisely, because you can point at it. Porting, reimplementing to a known spec, driving a test suite to green: the criteria are available before you start, so the loop has something real to terminate on.

It also makes it the opposite of agile. The start of a project is exactly the moment you cannot write acceptance criteria, because you don't yet know what you're building — that's what the early work is for. A loop that demands them up front asks for the one thing you don't have, precisely when you don't have it.

I don't think this is a bug I failed to fix. It's a property of the shape.

What I kept

The code stopped being the point. What I took out of it was a couple of months of hands-on work with the things that actually govern agent systems: token budgets, context management, and spawning subagents — what delegation costs, when it pays, and how quickly an unattended loop burns money when nothing tells it to stop.

The repo stays public as a finished experiment. It isn't maintained and I'm not taking issues, but the failure mode above is, I think, the useful part.

---

Running it

./ralph.sh                          # basic
./ralph.sh --budget 50 --warn-at 40 # with cost controls
./ralph.sh --dry-run                # show execution order only

Detailed flags, prompt format, queue directives and process templates are in AI-README.md, which is the working reference I wrote for the agent itself.