At Liquid Studio we have been working for a while with AI agents that write code on their own. You give them a list of tasks and an agent works through them one after another, without anyone having to watch each step. It has let us get through work that used to need much more attention. This article explains how we extended it to run multiple AI agents on the same project, in case you already work with agents or are thinking about it.
The more we used it, the clearer it became what was missing, and we boiled it down to two goals.
The first was quality. In a team, code doesn't go straight from whoever writes it to production: someone checks that it does what was asked, someone reviews how it is written, and then it gets merged. With a single agent, the one writing the code is also the one deciding the work is fine. We wanted each task to go through several stages, with a different agent doing each one.
The second was an overall view. In the usual setup, the task list lives in a file inside the project, on the machine where the agent runs. That makes it hard to see how development is going, review what has been done, add a task halfway through or put several agents on the same project. We wanted it all in one Trello-style board, with every project, the status of each task and its pull request, and different workflows depending on the kind of project.
The result is ralph-wiggums, which we have released as open source. Setting up the infrastructure an agent needs to work on real systems is also part of our artificial intelligence service. Below we explain how it works and why we made each decision.
Where we started: the Ralph pattern
We built on a pattern by Geoffrey Huntley called Ralph. It starts from an observation: an agent that works for a long time in the same session piles up failed attempts, files that no longer matter and discarded decisions, and reasons worse the more noise it carries. Ralph avoids this with a loop that starts a fresh agent for each task. The agent begins with no memory, does one thing and stops. Whatever it needs to know, it finds in the repository: the code, the git history and a spec.
Ryan Carson turned it into a tool, snarktank/ralph. A script reads a task list from a file, starts an agent for the next pending task and repeats. What each agent learns gets written to another file for the next one.
That is the base. Every change we describe below comes from something that didn't work for us when we used it.
Tasks in one central place
As long as the task list is a file on a single machine, nobody else can see its status, add tasks or work in parallel. So we moved it to a server with a small API.
The server stores projects and their tasks. For each task it keeps the spec, which a person writes and which is the reference for any decision; a minimal status with the stage it is in, its pull request and whether it is stuck; and a history of everything agents have done to it, with who worked on it, with what result and what they left in writing.
On top of the API there is a board with tasks in four columns: pending, in progress, stopped and done. Each card shows the task's stage, who is working on it, the link to its pull request and, if something goes wrong, the reason. Tasks can be edited or added while development is running, and agents pick them up on their next round.
Each worker also has its own view in the terminal. This is the one for a real project with 107 tasks, sorted by the stage each one is in:
Multiple AI agents without stepping on each other
With two agents on the same project, sooner or later both will pick up the same task unless something stops them. That is why the server does the assigning.
Each agent runs inside what we call a worker: the Ralph script on its own copy of the repository, on any machine with access to the server and to GitHub. When a worker asks for work, the server picks a task and reserves it for two hours. Picking and reserving is a single operation, so two workers never get the same task.
The assignment order tries not to waste work. A worker first gets the tasks it was already on, because it has the branch locally; then new tasks; and last, the ones another worker left behind. Within each group the most advanced go first, to finish before starting, and a task is never handed out while tasks it depends on are unfinished.
Only the script talks to the server. If the agent had access to the API, it could take a task that isn't its own or leave the status half-updated. So it receives its task details, does the work and leaves the result in a file, which the script validates before sending. The agent never sees the credentials.
Shared memory
Each agent starts with no memory, and one that doesn't know what the previous ones did ends up repeating work or breaking what already worked.
To avoid this, the agent gets, along with its task, the full history of that task and a summary of every task already finished in the project. The history tells it what was tried and what reviewers said. The summaries tell it where things are in the code: an agent starting a task on how the pieces of a game move already knows which file that code is in, because the agent that wrote it left a note.
Whoever writes the code doesn't approve it
If the agent that writes the code also decides it is finished, a misreading of the spec gets through without anyone noticing. So each task goes through several stages, and each stage is done by a different agent starting from scratch. The default workflow is a team's:
The first agent implements and opens the pull request. The second compares it with the spec without knowing how it was written. The third reviews code quality. The last one updates the branch, waits for the tests to pass, merges and writes the task summary.
Reviewers fix what they can on the same branch and approve. Tasks are small, so fixing things on the spot almost always pays off more than sending the work back. When the problem runs deeper, they reject the task and it goes back to the first stage with their comment in the history, which the next implementer reads before starting.
Each project defines its own stages. The server doesn't know what each one does; it only tells apart the first, which creates the pull request, the middle ones, which can reject, and the last, which closes the task. A simple project can stick to implementing and reviewing, and another can add a security stage. Adding a stage only takes writing its instructions.
While it works, the worker view shows the stages each task has gone through and what the agent is doing right now. In this screenshot, the code reviewer has just received pull request #184:
A test with Tetris
To try it out we wrote the spec for a Tetris game for macOS in Rust. It was about 400 lines covering the pieces, rotations, fall speed per level, scoring, controls and screen drawing. The starting project only opened an empty window.
An agent split the spec into twelve tasks and showed them to us before loading them. That was the only point where we stepped in, and it is where a person's judgement counts most, because how the work is split shapes everything that follows.
From the fourth task on we had Haiku, Anthropic's cheapest model, do the implementing, and kept Opus for the reviews. We wanted to see what happened with a weaker implementer and stronger reviewers.
The reviewers found three bugs. The collision check for the pieces was written twice, and the code reviewer merged it into one place. The second had to do with the floor: when a piece touches it, it has half a second to move, and each move resets that timer, up to fifteen times. Haiku's code let a player get around that limit by rotating the piece, so a piece might never lock. No test covered it; the reviewer fixed it and added the test. The third was caught by the reviewer that checks against the spec: new pieces took two seconds to show up on screen, the spec asked for something else, and the reviewer fixed it.
In a little over an hour of agent work we had a complete, playable Tetris, with a merged pull request for each finished task. Claude Code works out an equivalent cost of about 12 dollars; on a subscription, what gets spent comes out of the usage limit.
The Tetris built by the agents, running on macOS
When a task can't move forward
An agent working alone has no one to ask. If it gets stuck, it may invent a way out or keep going round in circles, so there is a response for each level of severity.
Faced with an ambiguity, the agent picks whatever fits the spec best and writes down its assumption for the reviewers to see.
When it can't move forward because the environment is broken, some access is missing or the spec contradicts itself, it marks the task as stuck and explains why. The task then goes to a specialised agent, which we call the doctor, that looks into the cause and decides what to do about it.
In the Tetris test this happened because of a mistake of ours: the spec gave two different speeds for level 1. The agent wrote no code and explained the contradiction. The doctor worked out which value was right, fixed the spec and the task carried on.
The limits are fixed so that no cycle repeats unchecked. A task rejected three times goes to the doctor, and the doctor steps in at most twice on the same task. If it can't solve it, the task stops along with the ones that depend on it and shows up in the board's stopped column, with the diagnosis.
Keeping usage under control
A Claude subscription has two usage limits, one that resets every five hours and a weekly one. A loop running on its own can use up the weekly one in a single night, so the worker checks its pace before each run. If it is going faster than would let it finish the five-hour window without going over 85 %, it pauses. If the next run would go over the limit, it waits for the reset, and if the weekly limit runs out, it stops.
In the Tetris test, the worker reached 31 % used an hour and three quarters into the window. Since it was going a bit fast, it waited three and a half minutes and carried on.
You can also choose which model does each stage. With two lines of configuration, the cheap model implements and the reviews use a better one:
RALPH_STAGE_IMPLEMENT=low
RALPH_MODEL_LOW=haikuIt is the combination that has worked best for us: the cheap model does the bulk of the work and the reviewers fix what it misses.
Three workers at once
The second test was a chess program for the terminal, with three workers in parallel and Haiku on every stage, reviews included.
Three different tasks needed the same file, and each one created it from scratch on its own branch. The first was merged without trouble and the second conflicted with it. The agent in the merge stage combined both versions, renamed a function that appeared in both, ran the tests, merged and wrote down how it had solved it for whoever had to merge the third.
One of the tasks went through all three workers. One implemented it, another reviewed the code and the third merged it, without any of them knowing about the others: the server gave each stage to whichever worker was free. That came to fourteen tasks in half an hour, at an equivalent cost of 65 cents.
Tuning the instructions
Agents make mistakes that repeat, and fixing each result by hand doesn't scale. Huntley suggests fixing the instructions instead, and compares it to tuning a guitar. It is the part that has taken us the most time, and we have almost never needed a new rule. Rewording an existing one is usually enough.
For example, agents only saw finished tasks, not pending ones, and sometimes left work "for a later task" that didn't exist. We fixed it by widening a rule they already had:
- **Decide instead of asking.** Nobody is there to answer.
+ **Decide instead of asking or deferring.** Nobody is there to answer, and no later task is promised.It pays to change as little as possible. Instructions that work are fragile, and a new paragraph can change behaviour that had nothing to do with what you meant to fix.
What it doesn't solve
The spec is still a person's job. Everything that went well in these tests started from specs with testable acceptance criteria; with a vague spec, agents fill the gaps with assumptions.
We have only used it on new projects. Huntley says the technique works best that way, and we haven't yet tried it on a large existing project.
Review between agents finds real bugs, but it doesn't replace a person's review. If the project matters, someone has to read the pull requests.
How to try it
The first thing you need is the task server. It isn't part of this repository, but its spec is: docs/central-prd-spec.md describes the API, the assignment rules and the board. It is short and can be implemented in any language. We built ours from that spec with a regular Ralph loop, with a single agent and the task list in a file.
With the server running, open Claude Code in your project and give it this prompt:
I want to use https://github.com/mbernet/ralph-wiggums to develop this project autonomously. Follow https://github.com/mbernet/ralph-wiggums/blob/main/SETUP.md
- Spec(s): <path to your spec>
- Ralph API: https://your-server/api/ralph
- API token: <token>
Get everything ready, then tell me briefly how to start the loop.The agent checks the environment, sets up a separate copy of the repository for the worker, turns the spec into tasks and shows them to you for review. When it is done it gives you the command to start.
Our advice is to start with a small new project, have the cheap model do the implementing and follow progress on the board.