Running Multiple Agents on One Repo Breaks It — Isolating Work Areas with Worktrees

When you run several Antigravity 2.0 agents against the same repository, you hit index.lock collisions and half-staged commits. Here is an isolation design using git worktree and projects that gives each agent its own work area, drawn from an incident I ran into in production.

agents⁸⁹ git-worktree³ parallel-execution⁵ isolation antigravity-2

✦ Premium Article

I once watched one of two parallel agents sweep up the other agent's commit and push it.

Because I run several sites and apps in parallel as an indie developer, it is tempting to fire off many Antigravity 2.0 agents at once — one adding articles, another bumping dependencies. But when I ran both on the same clone, the dependency agent's git add -A scooped up article files that the other agent had not yet staged, and unintended content landed on main.

I reverted it quickly, but tracing the cause led to a design flaw: I had run agents in parallel while they shared a single work area. This article lays out an isolation design for running multiple agents safely against one repository.

Why sharing a working tree breaks under parallelism

A git repository is made of three parts: the .git directory that holds history, the working tree where the files you are editing live, and the index (staging area) that records what goes into the next commit. The problem is that a clone has exactly one index and one working tree.

When parallel agents share a clone, three kinds of collision occur.

The first is the index.lock collision. git creates .git/index.lock while it rewrites the index. If agent B starts an add while agent A is mid-commit, B fails with Unable to create '.git/index.lock': File exists. In unattended VM runs, that failure tends to be swallowed silently, leaving you "thinking you committed" while nothing happened.

The second is working-tree contamination. Agent B's checkout overwrites files agent A is editing, or wipes them with git checkout ..

The third is the branch mix-up. A working tree can only point at one branch. The moment A switches to a feature branch, B is also working on that branch, and the changes tangle.

Give each agent its own work area with worktrees

All three share one root cause: a shared index and working tree. git worktree lets you keep multiple independent working trees and indexes while sharing a single .git (history). Assign one worktree per agent and you cut the collisions off at the root.

# Derive per-agent worktrees from a normal (non-bare) clone
REPO="$HOME/repos/antigravitylab.net"
cd "$REPO"
 
# Create a dedicated branch + dedicated working tree per agent
git worktree add "../wt-agent-articles"  -b agent/articles  origin/main
git worktree add "../wt-agent-deps"      -b agent/deps      origin/main
 
# Each worktree has its own index
#   ../wt-agent-articles  … article-adding agent only
#   ../wt-agent-deps      … dependency-update agent only

Now the article agent stages and commits only inside ../wt-agent-articles, and the dependency agent works only inside ../wt-agent-deps. Even a git add -A is scoped to that worktree's files. The incident I opened with simply could not happen with this separation in place.

Because worktrees share history, disk use is only the size of each working tree (tens of MB) — far lighter than holding two full clones.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Understand the mechanism behind the three collisions parallel agents hit on one repo: index.lock, working-tree contamination, and branch mix-ups

✦Take home a per-agent worktree layout plus a lifecycle script that covers cleanup, not just creation

✦Learn where to draw the operational boundary so you can safely run up to four parallel agents by combining Antigravity 2.0 projects with worktrees

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Putting worktrees on Antigravity 2.0 projects

Antigravity 2.0 added projects and worktree support, letting you switch units of work from the sidebar. In an "agent control tower" design where you supervise multiple agents, mapping "one worktree = one project = one agent" makes the independence of each unit visible on screen.

I have settled on this layout:

~/repos/antigravitylab.net        ← the "parent" clone for integration and push (humans only)
~/repos/wt-agent-articles         ← project: article agent
~/repos/wt-agent-deps             ← project: dependency agent
~/repos/wt-agent-i18n             ← project: translation-consistency agent

No agent works in the parent clone. A human (or a single integration agent) merges each worktree's feature branch into main in turn. Funneling pushes through a single point also avoids the non-fast-forward tug-of-war of several agents fighting over origin/main at once.

Manage the full lifecycle, including cleanup

Worktrees are easy to create, but if you forget to remove them, git worktree list sprawls and disk fills up. When an agent finishes, script the cleanup: merge the branch, then fold the worktree away.

#!/usr/bin/env bash
# finish_worktree.sh <worktree-path> <branch>
# Safely fold away a worktree whose branch is already merged
set -euo pipefail
WT="$1"; BR="$2"
REPO="$HOME/repos/antigravitylab.net"
 
cd "$REPO"
 
# 1) Refuse if the working tree has uncommitted changes
if [ -n "$(git -C "$WT" status --porcelain)" ]; then
  echo "⚠️ $WT has uncommitted changes. Aborting removal."
  exit 1
fi
 
# 2) Refuse if the branch is not yet merged into main
if ! git merge-base --is-ancestor "$BR" origin/main; then
  echo "⚠️ $BR is not yet merged into origin/main. Aborting."
  exit 1
fi
 
# 3) Remove the worktree and delete the spent branch
git worktree remove "$WT"
git branch -d "$BR"
git worktree prune
echo "✅ Folded $WT (deleted $BR)"

The key is to verify, before removal, that no uncommitted changes remain and that the branch is an ancestor of main (already merged). git merge-base --is-ancestor exits 0 when merged and 1 when not. Let the machine enforce the discipline: do not fold a worktree that fails this check.

How far should you parallelize?

Isolation does not license unlimited parallelism. In day-to-day operation, somewhere past four parallel agents the push-integration queue and your reviewing attention stop keeping up.

The realistic cap is not "number of agents" but "how many branches a human (or integrator) can safely merge into main within a given window." My baseline is three agents — articles, dependencies, translation consistency — plus one integrator. When I want more, I have found it more robust to widen each agent's scope than to add more agents.

Designing parallel agents goes faster, in the end, the more you nail "does not break" before "fast" — there is less rework. Next time you run multiple agents, start by giving each one its own work area with a worktree.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.