Running several AI agents on one repo

Two agents in one checkout do not work in parallel. They take turns, badly. A git working tree has one index and one HEAD, so once a second agent starts editing, both are staging into the same index, writing the same files and committing onto the same branch. There is no merge step, because there is nothing to merge — one agent's edit lands on top of the other's and nothing reports it.

The fix predates coding agents. git worktree checks the same repository out into a second directory, on its own branch, with its own index. Give each agent one and they share history and nothing else. This page covers the pattern by hand first, so you can run it with no tooling at all, then what DeckSpace automates around it.

The parts where the isolation stops are here too. A worktree solves a git problem, not a filesystem one, and the count of agents you ask for is a ceiling rather than a promise.

Why two agents in one checkout collide

Three things belong to the working tree rather than to the process using it. Each one fails differently.

• The index. Staging is per working tree. One agent running <code>git add -A</code> stages whatever the other has half-written, and the commit that follows contains both — attributed to one task.
• The files. Two agents asked to touch the same module will read it, think, and write back a whole file each. The second write wins silently. Neither agent saw a conflict, because git was never involved.
• The branch. There is one HEAD. An agent that checks out a branch moves the ground under the other one mid-edit.
• The build. A single <code>node_modules</code> or target directory, two agents installing and compiling into it at once.

This is why several terminal tabs opened in the same directory is not parallel work. It is the same serial work with the accounting removed. You find out at review time, if at all.

The worktree-per-agent pattern, by hand

You can run this today with git alone. Each agent gets a directory and a branch, and your own checkout is never written to.

1. Create a tree per agent: <code>git worktree add -b agent-1 ../work/agent-1 HEAD</code>. Repeat with a different branch and path for each one.
2. Start each agent CLI with its working directory set to that path. It now has its own index, its own HEAD and its own files.
3. Give each agent an explicit list of files it owns, and tell it not to touch others. Nothing enforces this — it is a prompt, and it is the weakest link in the pattern.
4. Before merging, predict the result without mutating anything: <code>git merge-tree --write-tree --name-only HEAD agent-1</code>. A non-zero exit lists the paths that would conflict.
5. Merge the one you want — <code>git merge --no-ff agent-1</code> — then remove the rest: <code>git worktree remove --force ../work/agent-1</code> followed by <code>git branch -D agent-1</code>.

Two costs are worth knowing before you script this. A new worktree has no <code>node_modules</code> and no build cache, so each agent starts with an install. And <code>--force</code> on removal overrides git's own refusal to delete a tree containing modified files, which is what makes a run disposable and also what makes it unrecoverable.

What DeckSpace automates

Swarm takes one goal, splits it into tasks, and gives each task a branch, a worktree and a terminal pane. The mechanics are the ones above, run for you.

• Each task gets a branch named <code>swarm/&lt;goal-slug&gt;-&lt;rand&gt;-&lt;n&gt;</code>, created with <code>git worktree add -b</code>.
• Worktrees are created under the operating system's temp directory, in a path keyed on both the repository and the full branch name so two repos with the same branch name cannot collide.
• If your project root has a <code>node_modules</code> directory, each new worktree gets a symlink to it instead of its own copy. On Windows that symlink needs privilege and is best-effort.
• The planner is asked for tasks that touch different files, and each task carries the paths it owns. That list is written into the builder's prompt.
• An optional Scout pass reads the repository read-only before anything is built, saves its report to project memory, and injects it into every builder's prompt.

Merge commits the worktree, snapshots your repository first, runs <code>git merge --no-ff</code>, then removes the worktree and deletes the branch. Discard runs <code>git worktree remove --force</code> and <code>git branch -D</code>, and throws away uncommitted work in that tree with no second prompt. Team works from a plan you approve first, on branches named <code>maestro/&lt;run-id&gt;/&lt;key&gt;</code>. It stops short of your working branch: the merged result lands on a <code>maestro/&lt;run-id&gt;/integration</code> branch and the run report hands you the <code>git merge --no-ff</code> line to run yourself.

The number you ask for is a ceiling

Four separate limits sit between the number you type and the agents that actually open.

• The roster accepts 1 to 12. The presets are Solo 1, Squad 5 and Fleet 12.
• The builder list is truncated to 12 before any worktree is created. That is the real cap, and it applies to a mixed-provider roster too — the per-provider counts are summed first.
• Panes max out at 16, shared with every other pane you have open. If the grid is full when a swarm launches, the builder does not start; its branch and worktree still exist and the log says so.
• Asking the assistant to launch a swarm reads a separate setting, <code>orchestrator_hard_cap</code>, which defaults to 8 and is clamped to 1 through 12. The Swarm room does not read it, so the same request made two ways produces two different fleets.

What the Sandbox setting does not cover

A worktree is an isolation boundary for git, not a fence around the process. Those are separate mechanisms with separate switches, and conflating them is the mistake worth avoiding.

• The Swarm room's Sandbox agents checkbox is passed to the headless calls only — Scout, the planner and the PR writer. It is not what confines a builder pane. The reviewer is a separate case: it is fenced whether or not the box is ticked, and it is launched in its CLI's own read-only mode.
• A builder pane's confinement comes from the app-wide write-confinement setting and from what your operating system actually provides. Each pane records the fence it received rather than the one that was requested, so an unconfined pane can be told apart from a confined one.
• The file-ownership split is advisory. Overlapping paths produce a log line before dispatch, and that line compares only what the planner declared — not what the builders go on to edit. It does not stop the launch.

The review gate before anything merges

Nothing reaches your branch because an agent said it was finished. Review on a task card runs four steps, and none of them touch your own branch.

1. The worktree is committed on its own branch. Your checkout is untouched.
2. The merge is predicted with <code>git merge-tree --write-tree</code> against your current HEAD. It writes objects but mutates nothing, and conflicting paths are listed on the card.
3. Your project's own checks run inside the worktree, then a reviewer agent returns a verdict whose first line must be exactly <code>APPROVED</code> or <code>CHANGES_REQUESTED</code>. A timeout or a missing verdict is not an approval.
4. Approved plus a clean predicted merge is what produces a green card. A predicted conflict or a failed check downgrades a clean approval to changes requested, and Merge relabels itself Merge anyway — the first click only arms it, and you have six seconds to click again before it disarms. An approval is also tied to a digest of the files it was given: if the worktree or the base branch moves afterwards the approval is dropped and you are asked to review again.

Review needs one of three CLIs installed — Claude Code, Codex or Antigravity — each launched in its own verified read-only mode. When more than one is present it deliberately picks a different one from the CLI that wrote the code, so the work is not graded by the model that produced it; with only one, it reviews with that same one. If none of the three is installed, Review stops and tells you to review the task manually. Team goes further and parks at a plan gate before anything launches — no worktree is created and no CLI is started until you approve the plan.

Where this stops working

The honest limits, in the order people hit them.

• Worktrees live in temp. macOS reaps that directory after a few days, so a saved run routinely comes back with its checkout gone. Those tasks lose their Review, PR and Merge buttons, because there is nothing left to review.
• Panes die with the app. Reopening the room adopts the previous run — the plan, branches and worktrees return — but nothing is spawned and no agent is relaunched.
• The workspace must be a git repository. Both Swarm and Team refuse otherwise, because both build on worktree branches.
• Unattended running depends on your CLI. Some agent CLIs publish no autonomy flag at all, and a builder running one of those sits at its own permission prompt inside its worktree until you answer it.
• Starting a run needs an active subscription. Opening the room and reading a previous run does not.