Many agents, one codebase works when every piece of work stays in its own files. Sooner or later two pieces need the same file: both add a route, both add to the same stylesheet. Then each worker gets its own branch in its own folder, and the branches go back into main one at a time, each checked before the next. Every command on this page was run for real in a scratch repository, and the outputs shown are what git printed.
Before you start
- (default) For each piece, pick its setup: the shared working copy, a worktree of its own, or a separate agent or session (the table below).
- (default) main always passes typecheck, the tests and the build, and nothing goes in that doesn't.
- (default) One branch per piece, named for it:
entry/timeline,fix/phone-overflow. - (default) Branches live for hours or days, not weeks: the longer one lives, the more it collides.
- (default) Generated files (lockfiles, build info, measured numbers) are regenerated after a merge, never merged by hand.
- (default) One owner merges. Workers commit on their own branch and report; they don't merge themselves.
- (default) Branches go in one at a time, and the checks run again after each.
- (default) Merged worktrees and branches are removed, so the next round starts tidy.
Pick the setup per piece
| The piece… | Setup | Why |
|---|---|---|
| lives in its own folder | the shared working copy | nothing to merge; how this library's 17 new entries were built |
| changes files another piece changes too | a worktree and branch of its own | each works undisturbed; conflicts are met once, at merge time |
| is an experiment you may throw away | a worktree and branch of its own | delete the branch and nothing is left behind |
| is a side task that needs everything decided so far | a fork of the conversation | it starts with the whole context, no brief needed |
| stands on its own | a fresh agent with a short brief | cheaper than a fork, and it tests whether the brief is complete |
| is a task someone will want to follow and steer | a session of its own | it outlives the conversation that started it |
A worktree per worker
A worktree is a second folder on a different branch of the same repository. Nothing is cloned and the history is shared, but each folder has its own files, so two workers never see each other's unsaved changes:
git worktree add ../lib-timeline -b entry/timeline
git worktree add ../lib-charts -b entry/charts
git worktree list
Each worktree is a full working copy, so it needs what a fresh clone needs. node_modules isn't shared: run npm install in each. Dev servers need a port each, or they take turns at the first free one and links stop matching:
npm install
npm run dev -- --port 5201
Merge in turn
Two workers, one route file and one stylesheet both changed, and the order that keeps main green. Step through it:
Interactive figure “merge-in-turn”: it runs in the full playbook in the library.
Three things make this go smoothly:
- The first branch fast-forwards. main hasn't moved since it branched, so merging only moves main forward.
--ff-onlymakes git refuse anything else, so a surprise merge can't sneak in. - The second branch rebases before it merges. Its commit is replayed on the new main, so the conflict is met in the branch, by whoever knows its change best, and not in main.
- The checks run between. After resolving, run typecheck, the tests and the build in the branch. A resolution that compiles can still be wrong: two routes, but only one style, say.
The resolution itself was keeping both sides:
.card { padding: 16px; }
.timeline { height: 48px; }
.chart { gap: 8px; }
Regenerate, don't merge
Some files are written by tools, not people. Merging them by hand produces something no tool would write. After any conflict in one, take one side and run the tool again:
| File | After a conflict |
|---|---|
package-lock.json | git checkout main -- package-lock.json, then npm install to add the branch's packages back |
*.tsbuildinfo | don't commit it at all: add it to .gitignore |
measured numbers (here costs.json) | take either side, then measure again on the merged code |
| previews, screenshots | capture again |
This repository did commit tsconfig.tsbuildinfo until this playbook was written. Every typecheck rewrites it, so any two branches would have conflicted on it. It is now ignored.
Forks, fresh agents and sessions
With AI helpers, "who does the piece" is a choice of its own:
- A fork inherits the whole conversation. It needs no brief, but it carries every assumption made so far, including the wrong ones, and its context is expensive.
- A fresh agent knows only its brief. That makes it cheaper and clean, and it shows you quickly whether the brief is complete. If an agent asks what you meant, the brief was missing something for everyone.
- A session of its own is a task that someone opens, reads and steers separately. Use one for work that ends in its own branch or pull request.
Whichever you choose, the rules on this page still apply. Each writer works on its own branch, and the owner merges in turn.
When it goes wrong
| What happened | What to do |
|---|---|
| Committed on main by mistake | git branch fix/name, then git reset --keep HEAD~1: the commit moves to the new branch and main goes back |
| A rebase is going badly | git rebase --abort puts everything back as it was before the rebase |
| A worktree's folder was deleted by hand | git worktree prune forgets the missing ones |
| A merge commit broke main | git revert -m 1 <merge> makes a new commit that undoes it, without rewriting history others have |
git branch -d refuses | the branch isn't merged yet: merge it, or use -D only if you mean to throw it away |
As of November 2026, in Claude Code: an agent can be given its own git worktree (
isolation: "worktree", removed again if it made no changes), and a fork inherits the conversation where a fresh agent starts from its brief. In the desktop app, a task can go to a session of its own, in its own worktree, with its own branch and pull request.