clone-per-agent

Run a bunch of coding agents on one repo without them stepping on each other in git. No new infrastructure, no vendor, plain git used the normal way.

The whole thing is one bash script and a git hook. It exists because I kept hitting the same wall running multiple agents in parallel, nobody I talked to was seeing it yet, and the fix turned out to be smaller than all the machinery I built before I found it.

The problem

If you run more than one coding agent at a time, they collide in git. The common move is to give each agent a git worktree. Worktrees share one underlying .git, which means they share the things git keeps per-repository, not per-working-tree:

• the refs namespace, so only one working tree can hold main
• the index
• packed-refs
• the stash
• a single checked-out working surface

Two agents racing through that shared state produce a familiar set of failures: one commits to the wrong branch, one rebases onto a stale base, one clobbers a file another was holding, the work-tracking gets corrupted. For two agents it is fine. At six on one machine the shared state dominates, and every fix you add is more machinery managing state that did not need to be shared.

The fix

Stop sharing .git. Give each agent its own full clone, created with git clone --reference against a local mirror.

--reference is the exact inverse of a worktree. It shares the object store (the blobs and trees, via alternates, not copied) while isolating everything that contends (refs, index, HEAD, working tree). So a clone is nearly free, and agents have nothing left to fight over. They coordinate the way a team of developers does: at origin, through pull requests.

Measured on a repo with roughly 80MB of history:

	cost
bare mirror (one-time)	82 MB
per-clone .git	688 KB
clone time	0s (objects referenced, not copied)

The mirror is cloned once, so the per-clone cost stays flat as history grows.

Layout

The container is a plain directory that holds the pieces. It is not itself a repo.

~/agent-clones/              container        (override with CPA_CONTAINER)
  .mirror.git/               bare --mirror of origin = shared object store
  main/                      canonical clone (tracks origin/main); read-only
  <branch>/                  one --reference clone per agent / task

Quickstart

git clone https://github.com/penacristian/clone-per-agent
cd clone-per-agent

export CPA_CONTAINER=~/agent-clones
./clone-per-agent.sh init https://github.com/you/your-repo

# make the canonical clone read-only (the structural guard)
cp guard-no-commit-on-main.sh ~/agent-clones/main/.git/hooks/pre-commit
cp guard-no-commit-on-main.sh ~/agent-clones/main/.git/hooks/pre-push
chmod +x ~/agent-clones/main/.git/hooks/pre-{commit,push}

# spin up a clone per task / per agent
./clone-per-agent.sh add fix-login-bug
./clone-per-agent.sh add refactor-api

# when a PR merges
./clone-per-agent.sh done fix-login-bug

Commands

command	what it does
init [<url>]	bootstrap the container, the mirror, and the canonical main clone
add <branch>	--reference clone off fresh origin/main, branch, run the post-clone hook
list	list the clones in the container
done <branch>	remove a clone, but only if its PR merged and the tree is clean (refuses to delete unpushed work)
mirror [<url>]	create or refresh the bare mirror only

Post-clone hook

The script stays ecosystem-agnostic. If you put an executable .cpa-postclone at the root of the canonical clone, it runs inside each new clone after setup, with the clone as the working directory. That is where your npm install, env-file copy, or codegen goes.

The hook must produce only gitignored artifacts (installed dependencies, build output). Anything it leaves as a tracked or untracked change makes the clone look dirty, and done refuses to delete a dirty clone, so it would never get reaped.

The other half: git-flow discipline

Cheap clones remove the contention. They do not, on their own, stop integration conflicts. The discipline that does:

One clone = one focused task = one short-lived branch = one PR. Branch off fresh origin/main, commit, open the PR, rebase before merge, squash, then done. Do not let a clone accumulate many commits over a long thread. Short branches keep rebases trivial and conflicts tiny. The clone is disposable, which makes this natural.

How it resolves the failures

failure	resolution
"only one main, branch-switching is a minefield"	each clone owns its refs namespace; two clones on two branches never collide
a stray git add commits unrelated files	no shared working tree exists; a file in one clone is invisible to another
stale base	every clone branches off freshly fetched origin/main
clobbered scratch / journal files	no shared working tree; nothing to clobber
"who is working on what" registry contention	the answer is open branches and PRs on origin (gh pr list); zero local machinery
wrong-branch commits	structurally impossible; clones are isolated, so branch-pin hooks become unnecessary

This removes surface area instead of adding it. The branch-pin hooks, the contended checkout, the work-tracking registry all go away.

Where this fits, and where it doesn't

In June 2026 Cursor announced Origin, a from-scratch git hosting platform built for swarms of AI agents, with numbers like 296,000 clones an hour and sub-400ms global sync. It is worth being precise about the relationship, because they are not the same thing.

Origin solves the server side. A host engineered to survive a swarm of agents hammering it in parallel. clone-per-agent solves the client side. Cheap local isolation so the agents on your machine do not contend. These are different layers, and they are closer to complementary than competing. Your isolated local clones can push to any host, including Origin.

The honest split, by scale:

• Small to medium scale (a handful of agents, a solo dev or a team): the client-side process is enough. Near-zero cost, no vendor, no lock-in, works on plain GitHub today. You do not need to reinvent git.
• Org scale (hundreds of agents, thousands of agent-generated PRs a day hammering one repo): the bottleneck moves from the client to the host, and a local technique does nothing for server-side contention. That is the problem a purpose-built forge is for.

I cannot benchmark Origin against this; it has not launched. What I can say is that we arrived at the same model from opposite ends. The unit of parallelism is the clone plus the pull request, and agents should coordinate at origin like a dev team. For most people, the simpler client-side version of that is all you need.

Honest tradeoffs

• The --reference gc footgun. A clone borrows the mirror's objects through alternates. Running git gc --prune on the mirror could delete objects a live clone still needs. The script disables gc.auto on the mirror and only refreshes it additively. gc the mirror by hand, and only when no clones are live. The long-lived canonical clone uses --dissociate so it never depends on the mirror.
• One install per clone. Same cost a worktree setup already pays. A shared package store (pnpm, a local npm cache) keeps it fast.
• Plain git, on purpose. This is not a new VCS. jj and Sapling solve some of the same problems, but they are a tool swap with their own footguns. clone-per-agent is git used the way teams already scale, which is the lowest-risk path.

License

MIT. See LICENSE.

Built by Cristian Pena.