Git worktrees: one brain, many agents working in parallel

Picture a single repository with several distinct concerns - a frontend, a backend, some infrastructure, the CI/CD wiring - and several agents working it at the same time, each on its own branch. You want them to move in parallel without standing on each other, and you want a central intelligence that can see all of their work at once: review one agent's diff, merge another's, resolve a conflict, keep the whole thing coherent. The naive answers both fail. Git worktrees are the answer that doesn't.

The problem: one checkout holds one branch

A normal clone can only have one branch checked out at a time. If agent A switches the working directory to its branch, agent B's files change underneath it - you've serialised everyone onto a single desk. The obvious workaround is N full clones, one per agent. That works, but each clone is its own .git: a full copy of history, its own remotes, its own fetch state. They don't share objects and they don't know about each other locally, so moving a branch from one to another means a round-trip through the remote.

N clones duplicate the whole history and can only exchange work through the remote. Worktrees keep one shared object store, so branches live side by side and any two can be compared or merged locally.

Worktrees are the middle path: one repository - one .git, one object store, one set of branches - with many working directories, each checked out to a different branch, all live at the same time. Isolation of working state, sharing of history.

What a worktree actually is

Think of a repository as a brain and a desk. The brain is .git: the object database, the refs, the config. The desk is the working directory: the files you actually edit. A normal clone bolts exactly one desk onto one brain. A worktree decouples them - one brain, many desks.

Each desk is a real directory on disk, checked out to some branch, with its own HEAD and its own index (staging area). But they all share the same object store, so there is no duplicated history and the disk cost of an extra desk is tiny. One rule keeps everyone safe: the same branch cannot be checked out in two worktrees at once. Git simply refuses - and that refusal is exactly what stops two agents from corrupting one branch.

One .git object store holds all history and all branches; each working directory checks out a different branch with its own HEAD and index. Add or remove desks cheaply - the brain is shared.

How it works

The whole interface is one subcommand. From inside your main repo you add a desk, point it at a branch (new or existing), and git creates the directory and checks it out:

# you are in the main repo (the "main worktree")
cd ~/work/app

# a desk for the backend agent, on a brand-new branch
git worktree add ../wt-backend -b feature/be-auth

# the frontend agent, its own new branch
git worktree add ../wt-frontend -b feature/fe-redesign

# the infra agent, off an existing branch
git worktree add ../wt-infra existing-infra-branch

git worktree list     # every desk + the branch each holds
git worktree remove ../wt-backend   # tidy up when done
git worktree prune    # drop stale admin entries

On disk you now have siblings - the main repo plus wt-backend, wt-frontend, wt-infra - each on a different branch. Under the hood the secondary desks don't carry a full .git directory; they hold a tiny .git file that points back into the main repo's .git/worktrees/<name>/. There is still only one object store. A branch created in one desk is instantly visible from every other, because there is only one repository.

Why this is the right substrate for many agents

The shared object store is the whole point. Because every branch lives in one database, a coordinating agent sitting in the main worktree can operate across everyone's work without touching a remote: git log --all sees all of it, it can diff any two agents' branches, cherry-pick between them, merge, resolve conflicts - all locally, instantly.

Parallel, isolated edits - each agent owns a directory, so there are no file collisions.
One branch per agent - enforced by git; the same branch can't be live in two desks.
Cheap to spin up and tear down - desks share objects, so creating or removing one takes seconds.
A central brain - one .git means one source of truth the orchestrator can reason over: every branch, every commit, the whole log.
Independent builds and tests - each desk has its own node_modules, its own build output and caches, so agents run their pipelines at the same time without clobbering each other.

That last point is easy to underrate. Separate working directories mean separate build state, so a frontend agent can run its dev server while the infra agent applies Terraform in a sandbox and the backend agent runs its test suite - none of them fighting over the same files.

Ways of working

Worktrees are a substrate, not a method. A few patterns map cleanly onto real teams and real agent fleets.

Orchestrator and workers

The main worktree is the central brain. It spawns one worker per worktree, each on its own branch. Workers commit to their branches; the orchestrator integrates - merge, rebase, cherry-pick across them locally - then pushes and opens the pull requests. This is the closest fit to "one intelligence, many agents".

The orchestrator lives in the main worktree and can see every branch at once. Each agent works in its own desk on its own branch; the orchestrator reviews, merges locally, then pushes and opens PRs.

One worktree per concern (long-lived) - wt-fe, wt-be, wt-infra, wt-cicd as semi-permanent desks that mirror your apps. Best when agents or teams map cleanly to subsystems.
One worktree per task (ephemeral) - spin a fresh desk for each feature or bug, throw it away on merge. Best when work is task-shaped rather than team-shaped.
An integration worktree - a dedicated desk where the orchestrator continuously merges everyone, to catch conflicts early. Your "does it all still fit together?" canary.

In Claude Code this is built in

If you drive agents with Claude Code, the worktree pattern is native rather than something you wire up by hand. A sub-agent can be launched with worktree isolation - it runs in its own auto-created worktree and the desk is cleaned up afterwards, which is the ephemeral pattern automated. There are also tools to move the current session into and out of a worktree. So "a central intelligence orchestrating N agents on N branches" becomes: this session is the brain in the main worktree, each spawned agent gets its own isolated worktree, and the integration happens back in the main desk.

Gotchas worth knowing

The same branch in two worktrees is blocked - by design. Give each desk a distinct branch.
Build artifacts are per-worktree - node_modules and the like are not shared, so each desk needs its own install. Usually what you want for isolation, but it is real disk and time.
Don't nest a worktree inside the repo - or git will try to track it as files. Keep desks as siblings (../wt-*), and ignore the pattern if you ever keep them inside.
Use git worktree remove, not rm -rf - deleting the folder by hand leaves a stale admin entry; git worktree prune cleans those up.
Hooks and config are shared - every desk reads the same .git/config and hooks. Usually fine, occasionally surprising.
Submodules add friction across worktrees - if your repo uses them, expect extra setup per desk.

The mental model is the whole trick: one brain, many desks. Stop thinking of a repository as a folder you switch branches inside, and start thinking of it as a single shared history that any number of working directories can read from at once. That is what lets a central intelligence coordinate a fleet of agents - each confidently on its own branch - while the history they all share stays the single source of truth.