How to run multiple coding agents in parallel

Three failure modes show up almost every time someone scales from one agent to several. None of them is a git problem, which is why worktrees alone do not fix them.

1. Port collisions

Your dev server listens on port 3000. So does the dev server in every worktree, because they all read the same config. The first agent to start its server wins; the second gets EADDRINUSE, or worse, a framework that silently picks the next free port, so the agent tests against a server running a different worktree’s code and reports a pass. Integration tests that bind a fixed port, a local database on its default port, and a Storybook instance all collide the same way.

2. Shared or missing node_modules

A new worktree contains only tracked files. There is no node_modules, no build output, and no .env. The agent either runs a full install in every worktree (slow, and on a Mac with many worktrees, a lot of disk) or you take the shortcut and symlink your main checkout’s node_modules into each one. The shortcut works until one agent adds a dependency and runs a clean reinstall: npm ci deletes node_modules before installing, and through a symlink it deletes the tree every other worktree is using. Orgabot’s own codebase records exactly that incident: one worker’s reinstall wiped the shared dependency tree and broke every parallel mission at once.

3. Unreviewed merges

With one agent, you read every diff. With five, you skim, and then you trust the summary. The summary says the tests pass. Sometimes the agent ran a subset, sometimes it ran them before its last edit, and sometimes it did not run them at all and is describing what it expects. Five branches arriving in an afternoon is where an unverified change gets merged, because the review step did not scale with the number of agents.

Orgabot is a local control plane that runs each task as a mission: you give it a project and an instruction, and it creates an isolated git worktree, runs a coding agent in it (Claude Code is the default worker), commits the result, checks it, and delivers it as a draft pull request. You can run several missions at once, and each one follows the same path. The overview explains the whole loop.

Registering a project once records the command that proves it works. After that, launching parallel work is one line per task, run from Orgabot’s framework/ directory:

npm run orgabot -- project add ~/code/myapp --verify "npm test"

npm run orgabot -- mission myapp "Add GitHub OAuth login" --background
npm run orgabot -- mission myapp "Fix the flaky checkout test" --background

npm run orgabot -- status             # every mission and where it is
npm run orgabot -- logs <mission-id>  # one mission's output

Or type the instruction into the dashboard’s mission terminal, which streams the agent’s output, lets you steer it mid-run, and treats Escape as an interrupt request that is only reported once the runtime acknowledges it. The first mission guide walks the whole path.

Here is how Orgabot handles each failure mode from above:

• Files: every mission gets its own real git worktree, created and cleaned up per task, so two missions on the same repository never edit the same files. When two missions on one project name overlapping file paths, the second waits for the first to merge instead of producing a conflicting pull request; disjoint paths still run concurrently.
• Dependencies: Orgabot gives each mission worktree its own node_modules by copy-on-write cloning your installed tree (APFS clonefile on macOS), so a reinstall in one worktree touches only its own copy. It is best-effort: if the clone fails, dependencies are simply absent and the verify step will say so.
• Load: a host-wide admission budget caps how much runs at once, checked before work starts. By default that is one coding-worker session per eight CPU cores (minimum one), one full verification run, and two light ones. Anything over budget is queued, never started and then paused.
• Checking and merging: covered in the next section, because it is the part worth the most.

Orgabot does not assign ports to dev servers you start yourself; if your agents run servers, give each worktree its own port as in the manual method. What the admission budget does mean is that two full test suites never run at the same time on your machine by default, which removes the most common test-time port collision. The dashboard documentation describes the budget and how to tune it.

If an agent dies or times out, Orgabot commits its work in progress to a salvage branch (excluding untracked node_modules, dist/ and similar build directories) so nothing is lost, and a mission that stops to wait for you keeps its worktree, branch, and session intact. The core concepts page defines each of these terms.

Isolation keeps parallel agents from breaking each other. It does nothing to stop any one of them from shipping a broken change. That takes checks that do not depend on the agent’s own report, and Orgabot runs three of them on every mission, in order.

1. Orgabot runs your tests, not the agent

After the agent finishes, Orgabot runs the project’s registered verify command (npm test, pytest, swift test, anything with an exit code) in the mission’s worktree, against the exact committed change. A non-zero exit fails the gate and the mission stops instead of shipping. The agent’s description of its own test run is never counted as evidence. One honest caveat: if a project has no verify command and none is detected, verification is recorded as skipped rather than passed, and it does not block, so set one.

2. A different agent reviews the diff

An independent reviewer reads the diff and raises findings. The reviewer is never the agent that produced the change, by rule rather than by convention. Findings go back to a fix round, which re-verifies and is re-reviewed, until the change converges. The shipping and review page covers the loop in detail.

3. Draft pull requests and approval policy

Editing a branch is automatic. Opening a pull request, merging, and deploying are not: they require policy or your explicit approval. Pull requests open as drafts on purpose, so the work lands in your normal GitHub review process instead of on your default branch. If a mission needs authority it does not have, it asks and waits rather than proceeding. The approvals guide and the list of invariants Orgabot will not weaken explain why.

When a check fails, the mission holds with a named reason and its worktree intact, and orgabot follow-up continues it on the same branch. A hold is Orgabot declining to guess, not a crash. The known limitations page lists what the current alpha does not do yet.