Isolation as Configuration

Three research agents into a Via mission, two of them modified the same file. Neither produced an error. The session log reported two successful writes, sequential timestamps, both marked complete. One of them was gone.

Not corrupted — gone. The second agent's write had silently replaced the first's. The combined output was worse than either agent's work alone, and nothing in the pipeline flagged it. I discovered it during review when I noticed the authentication module was missing a function I'd watched the first agent write.

That's the problem worktrees solve. Not elegantly, not completely — but more concretely than anything else available right now.

Via runs missions across parallel phases. A research phase fans out to five agents. A build phase fans out to three. At any given point I might have eight agents active in the same repository, each running with the conviction that it has a clean working directory. Before worktree isolation, that conviction was a lie. The agents were fighting over the same filesystem without knowing they were in a fight.

What Git Worktrees Are, Stripped Down

Git worktrees aren't new. The git worktree add command has existed since Git 2.5, released in 2015. The concept is simple: one repository, multiple checked-out working directories, each on its own branch. A developer could work on a hotfix in one terminal and a feature in another without stashing anything or cloning twice.

What Claude Code added on top of that foundation isn't the worktree mechanism — it's three things:

Standardized location. Worktrees land in .claude/worktrees/<name>. Every Claude session knows where to look. No configuration, no convention debate.

Branch naming. The branch is always worktree-<name>. Predictable, scriptable, and findable after the fact.

Declarative lifecycle management. This is the piece that changes the orchestration model. Add isolation: worktree to a subagent's frontmatter and Claude Code handles the create, the execution, and the cleanup — without a single line of orchestration code. The session exits, the worktree disappears if no changes were made. If changes were made, the orchestrator receives back the path and the branch name.

The command surface is small:

# Named worktree
claude --worktree feature-auth

# Auto-generated name
claude --worktree

# Open in a new tmux session
claude --worktree feature-auth --tmux

In subagent frontmatter, one field:

isolation: "worktree"

That's the entire API surface. One flag, one field.

The Primitive That Was Missing

I've been running Via missions since November. The orchestration model is phase-based: research phases fan out, build phases fan out, review phases consolidate. The agents share a task queue and write results back to a shared workspace through an atomic file-based IPC protocol. The coordination works. The concurrent file modification doesn't.

Before isolation: worktree, I had three options. Run agents sequentially — which defeats the purpose of a parallel phase architecture. Add explicit file locking — fragile, complex, and still vulnerable to agents that don't respect the locking protocol. Or accept occasional silent overwrites and catch them during review, which is what I was doing.

The declarative isolation field removes that third option from the acceptable list.

Claude Code is, as far as I can find, the first major coding tool to make isolation a declarative primitive rather than a manual workflow step. The comparison is instructive:

Cursor 2.0 is worth noting separately. Its Background Agents run in Ubuntu VMs — actual containers, not just separate working directories. That's a higher level of isolation than worktrees provide, and it requires cloud infrastructure to deliver. Claude Code's approach is local, lightweight, and one configuration field. They're solving for different scales.

The key difference from both: isolation: "worktree" is something an orchestration layer can set per-subagent, programmatically, without human intervention. An orchestrator spawning twelve parallel agents can give each one a clean filesystem in the same line of configuration that names the agent's role. Isolation as configuration, not coordination.

What This Enables

For Via-style multi-agent orchestration, three patterns become viable that weren't before.

Parallel phase execution with deterministic output. Two build agents can modify the same codebase simultaneously without race conditions on writes. Their outputs diverge from a known point — the base branch — and reconverge at merge. The non-determinism is bounded: agents can diverge from each other's assumptions, but they can't corrupt each other's files. Divergence is a solvable merge problem. Silent overwrite isn't a problem at all — it's a missing result that looks like success.

Specialized agent pools without synchronization overhead. The ccswarm pattern that practitioners have been exploring — Frontend, Backend, and QA agent pools each operating in their own worktree, coordinating through a shared task list — works without custom synchronization infrastructure. The isolation boundary is the worktree. The coordination boundary is the task queue. Those are separate concerns, and keeping them separate matters.

Failure containment. When a mission phase fails, I currently have to inspect whether the agent left the repository in a dirty state before rerunning. With worktree isolation, a failed agent's changes are contained to its branch. Rerun from the base branch. No cleanup step, no state inspection.

What It Doesn't Do

Worktrees provide filesystem isolation. They are not containers. Every agent in every worktree shares the same port space, the same Docker daemon, the same databases, and the same package cache.

Two agents running dev servers both try to bind port 3000. One fails, often silently, producing a test run against a stale server from a previous session. Race conditions on shared databases aren't prevented by file isolation. If two agents are writing migration files in separate worktrees and both try to apply them to the same development database, the result is non-deterministic.

The disk cost is also real. One practitioner documented 9.82 GB consumed by a single 20-minute Claude Code session on a roughly 2 GB codebase. That's a ~5x multiplier. Three parallel agents on the same codebase is 30 GB. Five is 50 GB. Disk is cheap until a CI runner runs out of space mid-pipeline.

The IDE detection gap affects interactive workflows. The /ide command fails to locate IDEs when the session is running inside a worktree path. Terminal-only workflows aren't affected. Mixed terminal-and-editor workflows are.

There's also a coordination problem that worktrees surface without solving: silent divergence until merge. Agent A adds a utility function to src/utils/format.ts. Agent B modifies src/utils/format.ts for a different purpose, not knowing about Agent A's addition. Both finish cleanly. The merge is a conflict. Worktrees didn't cause this — they made it visible instead of letting one agent silently overwrite the other. Visible is better. It is not solved.

The honest version: worktrees move the problem from "silent data loss" to "explicit merge conflict." That is a significant improvement. It is not a coordination solution.

What the Source Code Suggests

There's a detail that practitioners discovered by reading the Claude Code source directly: a TeammateTool with 13 operations — team spawning, inter-agent messaging, plan approval, and shutdown. It isn't documented. It isn't exposed through the command-line interface. It suggests Anthropic is building a coordination layer on top of worktree isolation rather than treating isolation as the end state.

That distinction matters for how to think about the current feature. isolation: worktree is probably a foundation, not a destination. A future where agent teams coordinate through explicit messaging channels — where the TeammateTool surface is public and composable — would use worktree isolation as the filesystem primitive underneath a richer orchestration protocol. The three things Claude Code added to standard git worktrees look, in that light, less like a finished feature and more like an infrastructure layer being prepared for something larger.

Honest Limitations

I've been designing Via's next orchestration phase around isolation: worktree. The feature flag breakage in February 2026 — widespread issues documented across multiple user sessions, mitigated by getting Claude Code to self-repair its own binary — reminded me I'm building on a platform that moves under my feet.

The more substantive limitation is methodological. This article argues that declarative isolation changes what parallel agent execution means for orchestration. That argument is built on reasoning about what the feature should enable, not on measured results from running the experiment.

There are zero empirical studies on whether parallel worktree agents produce better or faster output than sequential execution. That gap includes this article and it includes Via. I have a before-and-after intuition — the silent overwrite problem is real, and eliminating it should improve output quality in parallel phases. I don't have numbers. The assumption that more isolated parallelism produces better results is load-bearing across this entire space of tooling, and as far as I can find, nobody has published the controlled comparison.

I'll run the experiment. Via's phase-three orchestration architecture ships next week. When I have before-and-after quality metrics across parallel-with-isolation versus sequential-with-coordination, I'll publish them. Until then, the case for worktree isolation rests on eliminating a known failure mode — and on the observation that explicit merge conflicts are strictly better than invisible ones.

That case is strong enough to build on. It isn't the same as proven.