Worktree Isolation Became Table Stakes for Agent CLIs

Git worktree isolation for parallel coding agents stopped being a power-user trick this month. Inside roughly one week, three different agent CLIs put the same primitive in front of ordinary users — one isolated working tree per write-capable agent — and none of them framed it as an invention. Worktrees have been in Git for roughly a decade. What changed is who needs them.

The trigger is concurrency, not convenience. The moment you run two agents that can both edit files, a single shared working tree becomes a race: two processes read the same file, reason independently, and write back. The second write wins, and the first agent’s work disappears without an error, a conflict marker, or any other signal that something was lost. That is a classic last-write-wins bug, and it is exactly the class of problem a separate checkout removes.

This piece is about the pattern, not a vendor scoreboard. It covers why three teams landed on the same fix, what a worktree genuinely separates versus what stays shared, the two different granularities being shipped (per session and per subagent), what the isolation actually costs in disk and setup latency, and the situations where paying that cost is the wrong call.

The individual announcements are unremarkable on their own. Read together, they are the clearest signal yet that parallel write-capable agents have become a default assumption rather than an edge case.

GitHub’s Copilot weekly release notes, published August 7 for the August 3 release train, describe the new capability in one line: “Create an isolated worktree and begin a separate conversation with the new experimental /worktree command.” The same release added a sessions sidebar for managing concurrent conversations, a /rewind that works without Git, and a tool-call timeline with live duration metrics. Every one of those is a multi-session affordance. The worktree command is the part that makes multi-session safe.

Meta announced Muse Code on August 5. Its published architecture is described as “a simple agent loop plus a set of async background agents” that “remain active throughout each session, rather than being spawned for individual tasks”. The write-capable subagents have been characterised as each running in an isolated Git worktree — a per-subagent granularity rather than a per-conversation one — though Meta’s own announcement page does not spell out worktree mechanics in extractable detail, so treat the specifics as reported rather than documented. We already put Muse Code side by side with its peers in our comparison of Muse Code, Claude Code and Codex CLI, so this piece does not re-review it.

Claude Code is the one of the three that treats worktrees as settled surface area rather than a new arrival. Its documentation describes the workflow plainly: “Work on a feature in one terminal while Claude fixes a bug in another, without the edits colliding. Each git worktree is a separate checkout on its own branch, created from an existing commit, so the repository needs at least one commit first.” The invocation shown is claude --worktree feature-auth, and there is a separate worktrees page covering cleanup, a .worktreeinclude configuration file and support for non-Git version control — the shape of a maintained feature, not a flag someone added on a Friday.

Most engineers hear “two agents, one repo” and picture merge conflicts. Merge conflicts are the good outcome. They are loud, they block the operation, and Git hands you both versions. The reason worktree isolation became table stakes is the failure mode that produces no conflict at all.

A practitioner guide on parallel AI coding agents states the mechanism plainly: both agents may read the same file, generate edits independently, then write back — and the second write wins, erasing the first agent’s changes. There is no marker, no exit code, no diff to review. The work is simply gone, and the agent that lost it will happily report success, because from its point of view the write succeeded.

This is why the fix arrived as isolation rather than as locking or queuing. You could serialise agent writes behind a mutex, but that throws away the parallelism you were buying. You could have agents negotiate file ownership, but that requires every agent to be well-behaved and to know the blast radius of its own edits in advance — which is precisely what an autonomous agent cannot reliably promise. Giving each agent its own checkout removes the shared mutable resource entirely, which is the standard answer to a standard concurrency problem.

There is a second-order effect worth naming. Isolation converts an invisible data-loss risk into a visible reconciliation step. That is a genuine improvement, but it is a trade, not an elimination: you now own a merge that you previously did not have to think about, because previously one side of it had quietly ceased to exist. Teams that adopt worktrees and then complain about more merge conflicts are usually measuring the conflicts they were always generating and never seeing.

None of the three CLIs built a new isolation mechanism. They all wrap the same Git feature, and understanding what that feature does is the difference between using it correctly and assuming guarantees it never offered.

Git’s documentation is precise about the split: “The new worktree is linked to the current repository, sharing everything except per-worktree files such as HEAD, index, etc.” The object store — every commit, tree and blob in the repository’s history — is shared. What becomes private is the pointer state: which commit this checkout is on, what is staged, what the working directory contains.

The ref rules follow the same pattern, and Git spells out the exceptions: “In general, all pseudo refs are per-worktree and all refs starting with refs/ are shared. Pseudo refs are ones like HEAD which are directly under $GIT_DIR instead of inside $GIT_DIR/refs. There are exceptions, however: refs inside refs/bisect, refs/worktree and refs/rewritten are not shared.” In practice that means branches created in one worktree are visible from all of them, which is what makes merging back trivial — and also why two agents can still target the same branch name and collide if nothing stops them.

Two operational details matter for agent workflows specifically. Claude Code’s documentation notes that a worktree is created from an existing commit, so a repository with no commits at all fails — reported as Failed to resolve base branch "HEAD": git rev-parse failed. And Git provides both a lock (git worktree lock with a reason string) and a prune path (git worktree prune, plus the gc.worktreePruneExpire configuration) — those exist because worktree metadata accumulates. Locking and pruning are not optional polish; they are the admission that this primitive generates housekeeping.

The easiest mistake in reading this convergence is to flatten it. A worktree per conversation and a worktree per subagent solve overlapping but distinct problems, and they scale differently. One protects you from yourself across terminals. The other protects an agent’s own children from each other inside a single run — which is where the count of simultaneous checkouts can climb without a human deciding anything.

The table below places the three implementations against the same axes, using each vendor’s own primary as the source and Git’s documentation for the shared-state column. It is deliberately symmetrical: this is not a ranking, and the right-hand column is identical for all three because the unsolved problems are properties of the primitive, not of any vendor’s wrapper.

The asymmetry in that last column is the practical point. With session-level worktrees, a human decides how many exist and can feel the disk and setup cost directly. With subagent-level worktrees, the planner decides — and the cost curve in the next section is the one you inherit. If you are designing the orchestration layer above these tools, our write-up of multi-agent orchestration patterns that hold up in production covers how to bound fan-out before it becomes a resource question.

Vendor pages present worktree isolation as free. It is not, and the cost is predictable enough to write down as arithmetic rather than guess at. Because the object store is shared, you do not pay for repeated history — the repository’s commits exist once regardless of worktree count. What you do pay for is one checked-out working copy per worktree, and, critically, one dependency install per worktree.

That second cost is the one teams underestimate. The same practitioner guide makes the point directly: node_modules is per-worktree by default, because each worktree is a separate directory, so the package-manager install has to run separately in each one. Substitute your own ecosystem — virtual environments, vendored dependencies, build caches, generated clients — and the shape holds. Every worktree is a cold start.

The table below is pure arithmetic from that rule, not measured benchmark data. The N values are arbitrary points chosen to show the slope; they are not a recommendation and not an observed team average. Each derived cell follows the stated formula in its column header.

Read the columns against each other and the trade becomes obvious. The object-store column never moves, which is the whole argument for worktrees over per-agent clones. The install column moves in lockstep with N, which is the whole argument against creating them casually. If a cold install in your repository takes minutes, then fanning out to four isolated agents costs you four cold installs before any of them writes a line — and if the task itself is a two-file change, you have spent more time provisioning isolation than doing the work.

The mitigation is not exotic. Warm the expensive directories once and share them where your toolchain allows it, keep a small pool of long-lived worktrees rather than creating one per task, and make teardown automatic rather than aspirational — Git’s prune and lock commands exist precisely because stale worktree metadata otherwise persists indefinitely. Teams building this into internal tooling usually end up with a thin provisioning wrapper, which is the kind of glue our web development engagements tend to write early and then never touch again.

Three gaps survive the isolation, and all three are the kind that get discovered in production rather than in the changelog.

Design conflicts outlive branch separation. The same practitioner guide that describes the silent-overwrite failure is equally blunt about the limit: if two agents are both touching the authentication layer, even on different branches, you get merge conflicts and possibly conflicting design decisions. Separate checkouts stop agents from clobbering each other’s bytes. They do nothing about two agents independently deciding on two incompatible approaches to the same subsystem, and the second problem is more expensive to fix than the first.

The merge did not disappear. Isolation relocates reconciliation to the end of the run, where it is visible and reviewable — which is better, but it is still work someone has to do. Fan-out that ignores merge cost produces the classic pattern of four fast agent runs followed by an afternoon of manual integration. Bounding fan-out by how mergeable the outputs are, not by how many agents you can afford to run, is the discipline that makes the pattern pay. That is the same reasoning behind producer and consumer patterns for multi-agent work, where the coordination boundary is designed before the parallelism.

A worktree is not a sandbox. This is the one worth saying loudest. A separate checkout constrains where an agent’s Git writes land. It does not constrain what commands the agent runs, what it reads outside the repository, or where a symlink points. Isolation of the working tree and isolation of the process are different guarantees, and conflating them is how teams end up surprised.

The convergence makes worktree isolation look like a default. For genuinely parallel write-capable agents it is. For a large share of real agent usage it is overhead with no matching benefit, because there is no concurrency to protect against.

There is a fifth case that sits between these: agents that write only to disjoint, well-known paths — one generating fixtures, one writing documentation. In theory no isolation is needed. In practice the guarantee holds only as long as every agent’s scope stays honest, and agent scope drifts. If the paths are genuinely disjoint and enforced by tooling, skip the worktrees. If they are disjoint because the prompt said so, isolate anyway; a prompt is not a constraint.

Because the three implementations differ in granularity rather than in substance, the operational work is largely CLI-independent. Four decisions cover most of it.

One reported capability is worth flagging with a caveat. A third-party guide describes subagent-level worktree isolation in Claude Code configured through agent frontmatter, creating a fresh worktree per agent run and cleaning up automatically when the agent makes no changes. That behaviour was not something we could confirm on the official documentation pages we checked, so treat it as reported rather than documented and verify against current vendor docs before you build on it. The broader direction is not in doubt — agent surfaces are gaining execution-environment controls quickly, as the same week’s self-hosted runners and cross-session agent messaging release shows.

Looking forward, the interesting question is not whether more CLIs ship worktree flags — they will, and the flag is the easy part. It is whether isolation stays manual. Right now a human or a planner decides when to create a checkout. The obvious next step is for the harness to decide automatically from the write scope it has already computed: isolate when two pending edits could touch the same file, stay in one tree when they cannot. That would make the whole question disappear from the user’s view, the way transaction isolation levels disappeared from most application code. Until then, the decision is yours, and the arithmetic above is how you make it. Teams standing up multi-agent development workflows can bring us in through our AI and digital transformation engagements, where this is usually week one, not month three.