Git worktrees for parallel coding agents: an isolation playbook
Running two coding agents in one checkout is an easy way to create a confusing diff. One agent updates a dependency while another rewrites tests. Their edits land in the same working directory, build artifacts overlap, and neither session has a reliable view of what the other changed.
Git worktrees give each task its own directory, branch, HEAD, and index while sharing the repository's object database. They are faster and smaller than making a full clone for every task. The GitHub Copilot app runs parallel workspaces in dedicated worktrees and branches. VS Code can also start local Copilot, Claude, and Codex sessions in a new worktree.
A worktree isolates file changes. It is not a security sandbox, a container, or a substitute for reviewing the result.
What a worktree separates
A normal repository has one primary working tree. git worktree add attaches another working directory to the same repository. According to the Git worktree manual, linked worktrees share most repository data but keep per-worktree state such as HEAD and the index separate.
That separation solves the most immediate concurrency problem. An agent changing the payment flow does not see the uncommitted files from another agent updating documentation. Each task can run git status, stage files, and create commits on its own branch.
The shared parts still matter. Commits and refs created in one worktree are visible from the others. Git also normally refuses to check out the same branch in two worktrees at once. That guard prevents two directories from silently moving one branch tip in competing directions.
Dependencies, ports, and external services are outside Git's model. Two worktrees can still write to the same database, bind the same development-server port, reuse the same Docker Compose project name, or race on a shared cache. File isolation removes one class of collision, not all of them.
Create one task, one branch, one directory
Start from a clean, committed base. Then create a named branch and linked worktree:
git fetch origin
git worktree add -b agent/fix-oauth-timeout ../ish-chat-oauth origin/main
cd ../ish-chat-oauth
git status
The path and branch should identify the task. A predictable convention such as ../project-short-task and agent/short-task makes cleanup easier and reduces the chance that someone opens the wrong directory.
Give the agent a bounded job: the expected outcome, relevant files, validation command, and constraints. Do not ask two worktrees to modify the same subsystem unless you intend to compare alternatives. Worktrees prevent live file collisions, but overlapping commits can still conflict when you integrate them.
For a disposable investigation that should not create a branch, Git supports a detached worktree:
git worktree add --detach ../ish-chat-investigate origin/main
Use that for reading, reproducing a failure, or testing a hypothesis. Create a branch before keeping any commits you want to merge.
Account for the files Git does not copy
A new worktree begins from committed Git state. It does not contain uncommitted tracked changes or untracked files from the primary checkout. Git-ignored files such as .env, node_modules, virtual environments, and local certificates are absent too.
An agent's task may depend on a local configuration file that is missing from the new directory. Set up the worktree explicitly: install its dependencies, generate development configuration from a checked-in example, and inject secrets through the same secret manager used by other development environments.
VS Code offers a git.worktreeIncludeFiles setting that can copy selected ignored files into a new worktree. Its documentation warns that agent worktrees should receive only files the agent can safely access. Avoid a broad pattern that copies every ignored file. It can pull credentials, database dumps, or unrelated build output into every session.
Keep per-worktree runtime resources separate as well. Assign distinct ports, temporary directories, test databases, and Compose project names. If dependency installation is expensive, use a package-manager cache that is safe for concurrent readers instead of sharing a mutable installation directory without knowing how the tool behaves.
Know what isolation does not mean
VS Code's agent harness documentation states the boundary directly: worktree isolation does not restrict commands, network access, or access outside the worktree. An agent process may still read another directory if its permissions allow it, call external services, or run a destructive command.
Apply permissions independently from worktree choice. Limit credentials to the task, keep production access out of local agent sessions, review MCP servers and shell tools, and require approval for consequential actions. The least-privilege checklist for AI agent tools covers those controls in more detail.
Also treat generated changes as untrusted until reviewed. A separate branch makes the diff easier to inspect; it does not make the code correct. Run the project's formatters, type checks, tests, and security checks inside the same worktree where the change was made.
Integrate results in a fixed order
Before merging, make the agent leave a reviewable state:
git status --short
git diff --check
npm test
git log --oneline origin/main..HEAD
The exact test command will vary, but the handoff should always identify the branch, commits, files changed, tests run, and any unresolved risk. Review the diff from the integration checkout or through a pull request.
When several agent tasks started from the same base, integrate the least invasive or most foundational change first. Rebase or merge the next branch onto the updated base, rerun its checks, and resolve semantic conflicts rather than only textual ones. Two branches may merge cleanly while making incompatible assumptions about an API.
For a model comparison, give each model the same patch, prompt, and validation commands. ISH chat can compare reviews in one place, while the ISH API dashboard supports repeatable API-based evaluation. A constant workspace keeps the comparison focused on model behavior.
Remove worktrees without leaving debris
List every attached worktree before cleanup:
git worktree list
git worktree remove ../ish-chat-oauth
git branch -d agent/fix-oauth-timeout
git worktree prune --dry-run
git worktree remove refuses to remove a dirty worktree unless forced. That refusal is useful. Inspect untracked and modified files instead of deleting the directory manually. If a worktree was moved or deleted outside Git, git worktree repair and git worktree prune can fix or remove stale administrative records.
Submodule support remains incomplete according to the Git manual, so repositories that use submodules need extra testing before worktrees become the default agent workflow.
A practical policy is simple: use the current folder for one small interactive task that needs your uncommitted state. Use a new worktree for parallel or autonomous tasks based on committed code. Add a container or sandbox when the process itself needs stronger boundaries. Then merge one reviewed branch at a time and remove the worktree when the task is finished.
