If you have ever run two AI coding agents on the same project and watched them silently overwrite each other's work, you already know the problem. The fix is a git feature called worktrees, and once you understand how they work, the entire multi-agent workflow clicks into place.
what a worktree is
Normally, a git repository has one working directory. That is the folder where your files live, where you edit code, where your editor is pointed. When you check out a branch, the files in that folder change to match the branch.
A worktree is a second (or third, or tenth) working directory for the same repository. Each worktree is checked out to a different branch, has its own set of files on disk, and shares the same git history. Changes in one worktree do not affect files in another.
git worktree add ../my-project-feature-x -b feature-xThat command creates a new directory at ../my-project-feature-x, checks out a new branch called feature-x, and links it back to your original repository's .git directory. Both directories share the same commit history, remote configuration, and hooks. But their files are completely independent.
why agents need them
AI coding agents work by reading files, making changes, and writing those changes back. If two agents are pointed at the same directory, they are editing the same files. Agent A modifies auth.ts. Agent B modifies auth.ts. One of them overwrites the other. There is no locking mechanism. There is no conflict resolution. The last write wins.
Separate branches do not help here. Branches control which version of files you see when you check them out. But if both agents are operating in the same directory, they both see the same files on disk regardless of which branch they think they are on. You need separate directories.
Worktrees give each agent its own directory, its own branch, its own set of files. Agent A works in ../project-auth-refactor. Agent B works in ../project-billing-tests. They cannot interfere with each other. Their diffs are clean and reviewable independently.
the lifecycle
A typical worktree-per-agent session goes through four steps:
- → Create. Make a new worktree on a new branch. Copy environment files (
.env,.env.local) into the new directory so the dev server can start. - → Work. Start the agent in the worktree directory. The agent reads and writes files in isolation.
- → Review. Look at the diff. If the changes are good, commit and push. If they need adjustment, keep the agent going or make manual edits.
- → Clean up. Remove the worktree and optionally delete the branch.
git worktree removehandles this, but it will refuse if there are uncommitted changes.
This is straightforward with one agent. With three or five running simultaneously, the overhead adds up. You are creating worktrees, naming branches, copying env files, tracking which terminal has which worktree, reviewing diffs across multiple directories, and cleaning up when you are done. That is why agent managers exist: they automate this lifecycle so you can focus on the review step, which is the part that actually requires judgment.
worktrees on windows
Git worktrees work on Windows, but there are a few things to know:
- → NTFS path length. Windows has a 260-character path limit by default. Deep directory structures inside a worktree can hit this limit, especially in
node_modules. You can enable long paths withgit config --system core.longpaths trueand the Windows registry settingLongPathsEnabled. - → Symlinks. Some git operations use symlinks, which require developer mode or administrator privileges on Windows. Most worktree operations do not need symlinks, but if you see permission errors, enable developer mode in Windows Settings.
- → WSL repositories. If your code lives inside WSL (e.g.
\\wsl$\Ubuntu\home\user\project), worktrees should be created inside WSL too, not on the Windows filesystem. Crossing the WSL/Windows boundary for git operations is slow and can cause file locking issues. - → Port conflicts. Each worktree running a dev server needs its own port. If your project defaults to port 3000, you will get "address already in use" errors from the second worktree onward. Agent managers like Pane handle port isolation automatically.
automating worktrees with pane
Pane makes worktrees invisible. When you create a pane for a new task, Pane creates a worktree, checks out a branch, copies your environment files, and starts the agent you picked. When you close the pane, the worktree is cleaned up. You never run git worktree add or git worktree remove yourself.
This is not unique to Pane. Superset, Conductor, and Claude Squad all use worktrees for isolation. The differences are in platform support, agent compatibility, and workflow design. Pane is the only one that runs on Windows, Mac, and Linux and supports any CLI agent. See the worktree tools comparison for a full breakdown.
common patterns
- → One worktree per feature. The most common pattern. Each feature or bug fix gets its own worktree. Agents work in isolation. You review and merge each one independently.
- → Spike and discard. Create a worktree for an agent to explore an approach. If the approach works, keep it. If not, delete the worktree. The main branch is untouched.
- → Same task, different agents. Give two agents the same prompt in separate worktrees, then compare their approaches. Pick the better one or combine the best parts of each.
- → Long-running session. Keep a worktree alive for a multi-day task. The agent's terminal session persists across app restarts, so you can pick up where you left off.
For the practical walkthrough of running multiple agents in parallel, see How to Run Multiple AI Agents in Parallel. For the Windows-specific setup, see the Windows setup guide.