Feature Library
Playbook

Branching and forking

When parallel work has to touch the same files: a branch and a worktree per worker, merging them one at a time, and when an AI helper should be a fork, a fresh agent or a session of its own.

Updated 16 November 2026 · checked with git 2.55 and Claude Code, Nov 2026

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…SetupWhy
lives in its own folderthe shared working copynothing to merge; how this library's 17 new entries were built
changes files another piece changes tooa worktree and branch of its owneach works undisturbed; conflicts are met once, at merge time
is an experiment you may throw awaya worktree and branch of its owndelete the branch and nothing is left behind
is a side task that needs everything decided so fara fork of the conversationit starts with the whole context, no brief needed
stands on its owna fresh agent with a short briefcheaper than a fork, and it tests whether the brief is complete
is a task someone will want to follow and steera session of its ownit 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:

  1. The first branch fast-forwards. main hasn't moved since it branched, so merging only moves main forward. --ff-only makes git refuse anything else, so a surprise merge can't sneak in.
  2. 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.
  3. 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:

FileAfter a conflict
package-lock.jsongit checkout main -- package-lock.json, then npm install to add the branch's packages back
*.tsbuildinfodon'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, screenshotscapture 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 happenedWhat to do
Committed on main by mistakegit branch fix/name, then git reset --keep HEAD~1: the commit moves to the new branch and main goes back
A rebase is going badlygit rebase --abort puts everything back as it was before the rebase
A worktree's folder was deleted by handgit worktree prune forgets the missing ones
A merge commit broke maingit revert -m 1 <merge> makes a new commit that undoes it, without rewriting history others have
git branch -d refusesthe 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.