How it works
git worktree add attaches an additional working directory to one repository. Each worktree gets its own checked-out branch and its own index, but all worktrees share a single .git object database. You pay disk for source files, not for repeated copies of history.
The control loop for a fleet of coding agents:
- Create a worktree per agent, each on its own branch (
git worktree add ../agent-3 -b task/agent-3). - Point the agent's filesystem sandbox at that directory only.
- Let the agent edit, build, and test in isolation.
- Commit inside the worktree; the commit lands in the shared object store immediately.
- Integrate branches through your normal review and merge path.
- Remove the worktree (
git worktree remove) when the task closes.
Git enforces one invariant that matters here: a branch can be checked out in only one worktree at a time. That single rule is what stops two agents from silently sharing a working copy. Worktrees are cheaper than full clones — shared objects, no re-fetch — and stronger than a shared directory, because there are no cross-writes. Treat them as a filesystem isolation primitive, not a permission or network one.
Why it matters in an agent harness
When you run several coding agents in parallel, the failure you fear is interleaved writes: two agents editing the same file, one clobbering the other's half-finished change, a build that breaks for reasons neither agent caused. Worktrees remove that class of failure by construction. Each agent's edits are physically separate until a commit makes them explicit and reviewable.
That isolation buys the harness properties you actually care about:
- Reversibility: discarding an agent's work is
git worktree removeplus deleting a branch — no untangling of mixed changes. - Observability: each branch is a clean trajectory of one agent's commits, so diff review reads as a single intent.
- Blast-radius control: a runaway agent corrupts its own tree, not the shared checkout the others depend on.
- Bounded integration: separate branches force merges through review instead of letting concurrent edits land implicitly.
The cost is coordination. You still have to integrate N branches, and worktrees do nothing about network access, secrets, or destructive commands. Pair them with sandboxing and least-privilege credentials for those.
Git worktrees vs branches
| Git worktrees | Branches alone | |
|---|---|---|
| Working files | separate directory per branch | one shared checkout |
| Parallel agents | each edits in isolation | agents contend for the same files |
| Switching cost | none — directories coexist | git checkout stashes and rewrites files |
| Disk | source only, shared history | a single copy |
| Isolation guarantee | filesystem-level | none |
A branch is a pointer in history; a worktree is a physical place to work on one. For a single human switching context, branches suffice. For N agents editing at once, you need a working tree per agent, and that is exactly what worktrees provide.
The Rifty take
I treat filesystem isolation as the cheapest reliability win in a multi-agent coding harness, so every parallel agent gets its own worktree by default. I accept the coordination cost of integrating several branches because implicit shared-checkout writes are the failure I refuse to spend a night debugging. Worktrees are a boundary, not a sandbox — wrap them in permission and network controls, and let integration happen only through reviewed merges.
Common failure modes
- Assuming worktrees isolate anything beyond files — they do not gate network, secrets, or
rm -rf. - Two agents needing the same branch: Git blocks the second checkout, so provision a branch per agent up front.
- Orphaned worktrees after crashes; run
git worktree pruneand clear stale lock files. - Shared build artifacts or caches living outside the tree that quietly reintroduce cross-contamination.
- Long-lived branches that drift far from main, turning cheap isolation into an expensive merge later.
Frequently asked questions
How is a worktree different from cloning the repo for each agent?
A worktree shares one object database, so it skips re-fetching history and uses far less disk than a clone. A clone is a fully independent repository with its own remotes and objects. For parallel agents on the same repo, worktrees give the same file isolation at a fraction of the setup and storage cost.
Can two agents work on the same branch in separate worktrees?
No. Git enforces that a branch is checked out in at most one worktree at a time and blocks the second checkout. This is a feature: give each parallel agent its own branch. If two must collaborate on one branch, serialize them or coordinate through commits and merges instead.
Do worktrees sandbox an agent's permissions?
No. Worktrees isolate files within a repository and nothing more. They do not restrict network access, environment secrets, or destructive shell commands, and an agent can still reach outside its directory. Pair worktrees with real sandboxing, least-privilege credentials, and command guardrails for anything beyond file-level separation.
How do I clean up worktrees after agents finish?
Run git worktree remove <path> to drop a finished worktree, then delete its branch if the work is abandoned. After crashes, git worktree prune clears stale administrative entries and locks. Automate removal in your harness teardown so orphaned trees do not accumulate and confuse later runs.
When are worktrees not worth it?
When agents run fully sequentially, plain branch switching is simpler and worktrees only add filesystem clutter. They earn their keep under real parallelism, where isolated working directories prevent interleaved writes. If concurrency is your bottleneck, though, worktrees are the cheapest isolation primitive available.