Git worktrees vs sandboxes for running parallel coding agents

01What does a git worktree isolate, and what does it share?

A worktree is a second working directory attached to the same repository. Git's own documentation says a linked worktree shares everything with the main worktree except per-worktree files such as HEAD and the index. All refs under refs/ are shared, with a few exceptions such as refs/bisect, and by default the repository config file is shared too. So each worktree has its own checked-out files, its own staging area and its own current branch, on top of one shared history.

Git also adds a safety rule that matters for parallel agents: git worktree add refuses to check out a branch that is already checked out in another worktree, unless you pass --force. Two agents therefore work on two branches, and you merge the results the way you would merge any two branches.

Claude Code's documentation puts the scope plainly: worktrees isolate file edits. OpenAI's Codex documentation describes the same split: each worktree has its own copy of every file in the repository, while all of them share the same Git metadata.

• Separate per worktree: the working files, the index, HEAD and the checked-out branch.
• Shared by every worktree: the object store and history, most refs, and the repository config.
• Not touched by git at all: processes, ports, environment variables, your home directory and the network.

02How do Claude Code and Codex run parallel agents in worktrees?

In Claude Code, claude --worktree feature-auth creates a worktree under .claude/worktrees/feature-auth/ on a new branch named worktree-feature-auth. Running the same command with another name in a second terminal starts a second isolated session, which is the documented way to run multiple Claude Code instances on one repository. Subagents can get their own worktree too, with isolation: worktree in the agent's frontmatter.

A worktree is a fresh checkout, so gitignored files such as .env are missing and dependencies are not installed. Claude Code and Codex both read a .worktreeinclude file that lists gitignored files to copy into each new worktree. Codex keeps its managed worktrees in $CODEX_HOME/worktrees, keeps the 15 most recent by default, and saves a snapshot before deleting one.

Claude Code also adds checks of its own while a session is in a worktree: it blocks file edits that target the main checkout, commands whose working directory is the main checkout, and git commands redirected there. Its documentation is careful about the limit. None of those checks tracks which files a shell command writes, so a cp or a shell redirect into the main checkout is not refused by them.

03What leaks between worktrees when agents run code?

Everything that is not a file in the repository. Every worktree runs as the same user on the same machine, so each agent can read the same home directory, including SSH keys and cloud credential files, unless something else stops it. Two agents that each start a dev server on the same port collide, because there is one network stack. Two test suites that use the same local database or the same Docker daemon see each other's data.

Secrets multiply rather than shrink. When .worktreeinclude copies .env into each worktree, eight parallel agents means eight copies of the same keys, each readable by an agent that might follow injected instructions in a README or an issue.

The shared Git metadata is also a shared blast radius. Refs are common to all worktrees, so an agent that deletes or force-moves a branch changes it for every other worktree. Worktrees protect against agents overwriting each other's files; they were never designed to protect agents, or you, from each other's commands.

04What does a sandbox add for parallel agents?

A sandbox draws the line at the machine instead of the directory. Each agent gets its own filesystem view, process table, ports and network policy, so parallel agents stop colliding on ports and databases, and a hostile command reaches only its own sandbox. How strong the line is depends on the sandbox. Claude Code's built-in sandbox uses Seatbelt on macOS and bubblewrap on Linux. By default it limits writes to the working directory, a temp directory and folders you add, and sends network traffic through a proxy that checks each host against allowed domains that start empty.

Claude Code's documentation lists that sandbox's limits too: it covers shell commands only, so file tools, MCP servers and hooks run outside it, and by default reads reach the entire computer except certain denied directories, which still allows reading credential files. A VM-based sandbox moves the boundary further, giving each agent its own kernel and only the folders you share.

The cost of a sandbox per agent is setup. A fresh machine needs dependencies installed and services started, once per agent. Copying an already prepared machine, rather than building eight from scratch, is what makes machine-level isolation practical for many agents at once.

05When is a worktree enough, and when do you need a sandbox?

Ask what the agents will execute, not how many there are. If they mostly edit code and you run the tests yourself after review, worktrees solve the actual problem, which is edits colliding. If they install packages, run test suites, start servers or read untrusted text from the web, issues or dependencies, the risk sits in execution, and execution happens outside git.

Most teams end up using both. The worktree or branch stays the unit of review and merge. The sandbox becomes the unit of execution, where each attempt runs with its own processes, ports and network rules.

• Worktrees alone: agents edit code, you review every diff, nothing runs unattended, and the repository holds no secrets worth stealing.
• Add a sandbox: agents run tests, installs or servers in parallel, need different ports or databases, or run with approvals turned off.
• Add network and key controls: agents read untrusted content and could be told to send data or keys somewhere.
• Copy a prepared machine: setup is slow and you want several attempts from the same starting state.