How Project Swarm builds software with a team of AI agents

Coding agents are fast. They are also wrong in new ways. An agent can edit a file nobody asked it to touch, say "done" when no test ran, or keep spending while you sleep. We wanted the speed without trusting blind, so we built Project Swarm.

Project Swarm is an agent skill plus a Node.js runner with no dependencies. It is open source under the Apache 2.0 license. Verrow created it and maintains it, and it is hosted under our partner RDW Labz on GitHub. It grew out of a real website build, and it is the build system behind our projects today, including this site.

One coordinator, many workers

Every run has one coordinator. That can be a person or a coding agent: Claude Code, Codex CLI, Cursor, Gemini CLI, or another agent that can read files and run commands. The coordinator decides the tasks, supplies the context, reviews what comes back, integrates it, and checks the final product.

The workers do the scoped pieces. Each worker is a fresh process or a single API request. Workers do not share a conversation. If a follow-up needs an earlier answer, the coordinator passes it in on purpose.

Before any model call, the kickoff asks the owner two questions: which model providers may receive the project's code, and what the spend ceiling is. Nothing is dispatched until those answers are recorded.

A mission becomes scoped jobs

A large goal is too much for one job. The coordinator splits it into jobs that each have:

• one clear deliverable,
• the exact files the worker may read,
• the exact files it may write, with one writer per file,
• and a check that shows the job worked.

File lists name real files, not folders or wildcards. Paths that climb out of the project, symlinks, .git, .swarm and .env files are refused. If another live run on the repository is already writing one of a job's files, the new run will not start.

When parallel jobs must agree on a name, the coordinator writes a contract file first. A worker that needs a name it lacks reports the gap instead of inventing one.

For larger builds, you write one scope file where each requirement is a testable sentence with acceptance criteria. The swarm splits it into small tickets, you approve the plan once, and it builds the tickets in waves.

Lanes, tiers and escalation

Not every job needs the most expensive model. Each job can carry a tier:

• Cheap: small follow-ups, summaries, pull request text, bookkeeping.
• Mid: code and tests against a clear written contract. The default.
• Expensive: a new design with no clear contract, or a step a mid-tier worker already failed twice. It needs a written reason.

Each agent has its own lane with its own limits. A job set to "auto" goes to the cheapest healthy lane that can take it. After two failed or timed-out attempts on a lane, it moves up. In the scope flow, a failed ticket climbs a ladder: a bigger output allowance, then a different agent, then the expensive tier. Only when the top step fails is the ticket blocked, with the reason recorded. The expensive models only see the problems that earned them.

Which agents it can drive

The runner has thirteen adapters. Claude Code, Codex CLI and Cursor CLI work on code. Hermes and Qwen Code run as tool-free CLI workers. OpenAI, Gemini, Ollama, Lambda, OpenRouter and Anthropic run as API jobs. A local adapter takes any OpenAI-compatible endpoint, and a rented adapter takes a GPU server you rent and run yourself.

They do not get the same powers. Codex and Cursor writers, and Claude jobs with a shell, work in their own git worktree under a macOS sandbox. Other Claude jobs work on a copy of only the files they were given. API workers get text in and must return complete files in a strict JSON format, with no tools at all. Jobs are sensitive by default, and only a job marked not sensitive can go to OpenRouter, OpenAI, Gemini or Lambda.

Isolated workspaces

Every worker sees the project as it was when the run started. A job whose files changed before dispatch fails instead of working from a stale copy.

The project's security notes say plainly that copied workspaces are not an operating-system security sandbox. They cut down accidental scope creep and unsafe merges. They do not replace host access controls. So the rule is simple: secrets never go into a worker's context.

There is also a guard on the coordinator. An orchestrating session may not hand-edit the product's source without the owner's approval for named files. Build work goes through the swarm, where it gets reviewed.

Review and the merge guard

A model saying "done" is not proof. Worker text is treated as untrusted data, never as commands to run.

When a run finishes, the coordinator inspects every proposed file. Integration imports only the files a job declared, checks that each target is unchanged since the run began, refuses missing outputs, and never applies a deletion. One conflict blocks the whole set. Then the project's checks run. If they fail, nothing is kept. For large runs, a merge queue checks work in batches, rolls back a batch that fails, and splits it to find the job that broke it.

The last step is the merge guard. swarm merge refuses a pull request unless every check on it is green. Failing counts. Pending counts. A required check that has not reported counts. There is no flag to skip it: --force, --admin and --skip-checks are all refused.

The security gate and spend caps

Every batch passes a security gate before it can stay merged. It runs before the project's own checks, so a blocked batch never runs its code. It scans written files for secrets. It checks that each new dependency exists on the registry, is at least 30 days old, has at least 100 weekly npm downloads, and does not imitate a popular name. It checks known vulnerabilities when a dependency file changes, holds install-script changes for the owner, and blocks GPL and AGPL licenses unless the policy allows them. If the gate errors, it fails closed and nothing is written.

Money gets the same treatment. A job starts only if what has been spent, plus what is reserved for running jobs, plus this job's worst case, stays under the cap. Caps can be set per run, per project, and per lane per day. OpenRouter starts at $5 per day. At a cap, new launches stop, running jobs finish, and the run waits. Raising a cap needs the owner's OK and a written reason. swarm stop --all halts everything at once.

Every mistake becomes a test

When a real run hits friction, it is written down as a lesson. Where possible, the lesson becomes a check in the tool, pinned with a regression test so the mistake cannot slip back in. Lessons that share a theme can be grouped into a proposed guard, but a person builds it and opens the pull request. Nothing merges automatically.

Past lessons also feed new work. A ticket's job can get up to three short "watch out for" notes from the most similar lessons. A small set of evaluation tasks, each rebuilt from a real failure, keeps score, and a change to prompts, guards or models does not merge if that score drops.

How this site was built

Verrow.ai is built with Project Swarm, and so is our client work. The coordinator works from a task list and a running handoff, and any agent can pick up where the last one stopped with swarm brief, which prints the goal, what is done, what is running, and the next commands.

Get it

Project Swarm is public at github.com/RDW-Labz/project-swarm (opens in a new tab). You do not need a GitHub account to clone it. It needs Node.js 20.3 or later on macOS, Linux or WSL, plus one configured provider. There are no npm packages to install.

Start with the kickoff prompt in the README. Run the two small smoke jobs, read what came back, and only then hand it real work. Each live worker bills your own provider account, so set a cap first.

Related work

Related services: AI agents · Custom software