Git worktrees give parallel coding-agent tasks separate working directories and branches, but they are not separate repositories or security sandboxes. They start from committed state, usually omit ignored local files, and still share repository data. The commands below show an illustrative setup—not code from a verified incident. The title’s “what broke” is best answered as a set of documented failure modes and safeguards, not as a claim about a particular outage.
What Git worktrees isolate—and what they share
A linked worktree is another checkout attached to the same Git repository. Each worktree has its own working directory and per-worktree state, including its current HEAD and index. Most repository data and most refs are shared, though Git documents exceptions. That makes worktrees useful for keeping concurrent edits in different directories without duplicating the repository’s full object database.
This is location isolation, not a general-purpose boundary around an agent. A worktree does not by itself restrict commands, network access, credentials, running processes, databases, or other external services. VS Code’s current agent guidance makes the distinction directly: “Worktree isolation keeps changes out of your active workspace, but it does not restrict the commands or network access available to the agent.” Use an operating-system sandbox or other appropriate controls when those restrictions are required.
Create separate worktrees for independent tasks
Start from a known local base commit or branch. The following illustrative commands create two new branches and worktrees from main; they are not a reproduced incident or a universal project setup script.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
git worktree add -b agent/task-a ../repo-task-a main
git worktree add -b agent/task-b ../repo-task-b main
git worktree listConfirm the listing shows the intended, distinct paths and branches before launching agents. If main is not available locally, choose a base that is. Git will not let the same branch be checked out in another worktree as if it were an independent branch.
Before parallelizing, define each task’s observable outcome, files in scope, acceptance criteria, behavior to preserve, exclusions, and validation. Separate directories help prevent accidental edits to the active checkout, but they do not make overlapping changes compatible.
Rank #2
What can break in practice
The agent’s worktree is missing inputs
A new worktree is populated from its selected committed base. It does not automatically inherit uncommitted tracked edits or untracked files from the main checkout. Ignored files—often local configuration such as .env files or installed dependencies—are also absent by default. A task can therefore fail to build or test even when the primary checkout works, because that checkout relied on local state that was never committed or recreated.
Make required shared code part of the base commit, or provide a repeatable setup process for every worktree. If a task genuinely depends on current uncommitted context, consider doing it in the active folder rather than assuming a fresh worktree will contain that context.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesIgnored dependencies are copied or shared unexpectedly
VS Code documents experimental options to copy selected ignored files, with patterns such as .env or node_modules/**, and to symlink eligible ignored folders. Copying gives a task its own files, at the cost of additional setup or storage. A symlink saves duplication but points to shared content: edits made through it affect the original folder and any other worktree using that target.
Use a copy when tasks need independently mutable dependency state. Symlink only when every user of the target can safely share changes. Treat configuration and secrets especially carefully; do not copy production credentials into agent worktrees.
Separate directories are mistaken for separate environments
Worktrees do not isolate services, databases, ports, processes, or network destinations. Two agents may use separate source trees while still writing to the same development database or reaching the same API. For browser and end-to-end tests, configure and verify the intended API, data, and test environment explicitly; a different checkout path does not prove that a test is using separate services.
Clean individual changes conflict after integration
Two branches can each pass tests alone and still fail together because they changed overlapping interfaces, assumptions, dependencies, or shared configuration. Parallelism is most useful when tasks are independently implementable and testable against the same known-good baseline. Review each result separately, integrate through the team’s normal process, and run validation again on the combined result.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Best Value
A 2026 preprint by Qian et al., “Effective Strategies for Asynchronous Software Engineering Agents,” discusses concurrent edit interference, dependency synchronization, and integration as broader challenges. Its CAID evaluation reports absolute improvements over single-agent baselines of 26.7 percentage points on PaperBench and 14.3 percentage points on Commit0. Those results concern a structured approach combining centralized delegation, asynchronous execution, isolated workspaces, and executable verification; they are not evidence that worktrees alone produced the gains or that any particular incident occurred.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose worktrees, copying, or serialization based on the task
| Choice | Use it when | Main trade-off |
|---|---|---|
| New worktree | An independent task should not edit the active workspace and can start from committed state. | Provides a separate checkout path, but local uncommitted context and ignored files are not automatically included. |
| Active folder | A small interactive task depends on current uncommitted files or local context. | Preserves that context, but the task shares the active working directory and its edits. |
| Copy ignored dependencies | A task needs its own mutable copy of ignored files or dependencies. | More setup or storage, with less cross-worktree mutation risk. |
| Symlink ignored dependencies | Agents can safely use and modify the same ignored folder. | Less duplication, but changes through the link affect the shared target. |
| Serialize tasks | Tasks overlap heavily, depend on the same changing files, or rely on shared state that cannot be separated safely. | Less concurrency, but avoids some parallel coordination and integration risk. |
Review, integrate, and clean up safely
- Prepare the baseline: use a clean, known-good commit and run the relevant baseline tests before creating agent sessions.
- Check each session: verify that every agent has a different worktree path and branch. Stop and correct the setup if two sessions point at the same directory.
- Review each branch: inspect its changes against the task scope and run the task’s stated checks. Preserve any changes you want before removing a worktree.
- Integrate and retest: merge or otherwise integrate reviewed work using the team’s normal process, then validate the combined code and any shared services it uses.
- Remove a finished worktree: run
git worktree remove <path>after preserving desired changes. Usegit worktree list --porcelainwhen a machine-readable inventory is useful.
Do not casually move or delete linked worktree directories outside Git. If a worktree was moved manually, git worktree repair can restore its connection. If it was deleted manually, stale administrative records can be cleaned up with pruning; git worktree prune is the relevant maintenance command. git worktree lock can protect a worktree on a temporarily unavailable device or share from being pruned.
Git compatibility and submodule caveat
The Git worktree manual documents lifecycle commands including add, list, remove, lock, move, repair, and prune. It also warns: “Multiple checkout in general is still experimental, and the support for submodules is incomplete. It is NOT recommended to make multiple checkouts of a superproject.” This is a documented caveat, particularly relevant to repositories using submodules; it does not mean every ordinary worktree operation is unusable.
Git configuration is generally shared as well. The extensions.worktreeConfig extension can make selected configuration worktree-specific, but older Git versions refuse repositories that use it. Check the Git versions used across your team and automation before enabling it.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
