Anthropic Says: One Worktree Per Agent. Your Infrastructure Says: Not So Fast.

Anthropic’s Claude Code documentation now treats a git worktree per agent session as the default pattern for running parallel agents. The recommendation is sound for the file system layer. But platform teams running multi-agent workflows are discovering it doesn’t solve the runtime collision problem underneath it.

How It Works

Git worktrees give multiple working directories from a single repository — one .git database, multiple checkouts. Without them, three Claude Code agents working simultaneously edit the same files on the same branch: changes collide, context gets corrupted, and the agents interfere with each other’s work.

Anthropic’s February 2026 announcement of built-in git worktree support in Claude Code addressed the file system problem. Each agent session gets its own working directory, isolated at the git layer. That’s a real improvement for developers running parallel coding tasks.

The infrastructure problem surfaces one layer below. When multiple agent sessions run simultaneously on the same machine, they share ports, databases, caches, secret stores, and test state. Agent A’s test suite might start a local Postgres instance on port 5432. Agent B’s test suite tries to do the same. The git worktree isolation doesn’t extend to these runtime resources.

What This Means for You

The gap between “worktrees are recommended” and “worktrees are sufficient” grows with the number of concurrent agents and the complexity of the services each agent’s workflow depends on. For a simple coding agent that generates code and runs unit tests with no external dependencies, worktrees are enough. For agents that spin up databases, make external API calls with rate-limited keys, run integration test suites, or write to shared caches — worktrees solve the file layer but leave the runtime layer unmanaged.

The New Stack’s analysis identifies the pattern: agent-native runtime infrastructure requires per-agent isolation not just at the code level but at the process, port, credential, and state level. Some teams are addressing this with container-per-agent patterns — each agent session runs in a fresh container with its own runtime environment, networked isolation, and ephemeral credential injection.

For platform teams building agentic sandbox infrastructure, the worktree recommendation is the starting point, not the destination. The complete isolation stack looks like: worktrees for code isolation + containers or VMs for runtime isolation + scoped credentials for secret isolation + ephemeral test databases for data isolation.

Source: The New Stack

Content created with AI assistance and reviewed for accuracy.