Back to all posts
·4 min read·Like or comment

Autonomous AI Coding with the Ralph Loop

Get new posts by email. No spam, just an email when I publish something new.

TL;DR

  • Ralph is an autonomous AI coding loop made of a bash script, a seed prompt and a todo folder of markdown task files.
  • Each iteration an agent claims a pending task, completes it, writes notes, then commits and pushes. Failed tasks go back to pending for a retry.
  • It works because tasks are small and self-contained, failures are recoverable, and progress is committed incrementally.
  • It built a functional (though not production-ready) in-browser Excel clone in about an hour.
  • The developer's job shifts from writing code to breaking problems down and writing clear specs.

Since Geoffrey Huntley released his work on Ralph, and Steve Yegge on Gas Town, I've been experimenting with an autonomous AI coding loop called Ralph. It built a working Excel clone that runs in the browser in about an hour. I put together a ralph-demo repo on GitHub so you can try it yourself. It's just a bash script, a seed prompt and a todo folder.

How it works

You break a large project down into small tasks, each one a markdown file in a todo/ folder. A bash loop then runs an AI agent over and over, and each time around:

  1. The agent looks for a file ending in .pending.md
  2. It "claims" the task by renaming it to .processing.md
  3. It reads the task and does all of it
  4. It renames the file to .completed.md with notes about what was done
  5. It commits and pushes the changes to git
  6. The loop moves on to the next pending task

If the agent can't finish a task, it renames the file back to .pending.md with notes about what went wrong, so the next run can retry it.

The seed

It starts with a simple planning step. You give the AI a high-level description of what you want to build. In this case:

"I need you to plan an application to build. It's going to be like Excel - but in a browser. Have phases where the important features are done in the first phase and so on."

The AI then breaks this down into tasks with dependencies, filling the todo/ folder with .pending.md files that describe each piece of work.

Why it works

This gets around a few problems with AI coding:

Each task stands alone. The agent doesn't need to hold the whole project in its head, just the current task and what it requires. There's a limit to how much an agent can keep in memory at once, and that limit hurts on long, complex coding sessions.

Failures are recoverable. If one run fails, the task goes back to pending and the loop continues. It can recover from agent errors, timeouts and half-finished work.

Progress is saved as you go. Each completed task is committed and pushed. You can stop the loop at any time and still have working, versioned code. So you won't lose hours of work to a crashed session.

It could run in parallel. It does one task at a time right now, but the same setup would let multiple agents run at once, each claiming different pending tasks.

What this means for developers

What struck me about Ralph is how it changes the developer's job. Instead of writing code, you're writing task descriptions and reviewing commits. The skill becomes breaking problems down well and writing clear specs.

Senior developers already work a bit like this, spending more time on architecture and requirements than on writing the code. Ralph just takes it further.

The Excel clone wasn't production-ready, but it was on the right track with the basics working. It could've gone further if I'd let it burn through more tokens. So I think we'll soon be measuring the cost of software in API credits instead of developer hours.

Try it yourself

The ralph-demo repo has everything you need to get started. It's simple enough to recreate or adapt. You need:

  1. A seed prompt that asks the AI to break your project down into task files
  2. A bash loop that runs an AI agent with a prompt telling it to claim, do and complete tasks
  3. A todo/ folder that uses .pending.md, .processing.md and .completed.md file names

AI agents work better with clear, small tasks than with open-ended coding sessions. Put the task queue in the filesystem, let the agent work through it, and the results hold up well.

This feels like an important pattern, for AI coding and for how we'll work with AI in general. Give agents some structure, let them work in small steps and plan for things going wrong.

More to read