Git worktrees on Windows, without the pain

Worktrees are the best way to isolate parallel agents. On Windows they come with a few traps — path length, dependencies and cleanup. Here is how to avoid them.

A Git worktree is a second working directory for the same repository, checked out on its own branch. For parallel agents it is ideal: each agent gets a real directory, a real branch and the full history, and none of them can overwrite the others.

On Windows, worktrees work well — once you know about three traps.

Trap 1: path length

Windows still has a 260-character path limit for many programs unless long paths are enabled. A worktree in C:\Users\you\projects\my-app-worktrees\fix-the-flaky-upload-test\ plus a deep node_modules path can cross it quickly. The symptom is confusing: an install or a build fails with “file not found” for a file that clearly exists.

What helps:

  • Keep worktree roots short. PaneScale puts lanes under a one-letter folder in its data directory and names each lane with a short run id plus a trimmed label.
  • Enable long paths in Windows (the LongPathsEnabled policy) and in Git (git config --global core.longpaths true). PaneScale’s autopilot preflight warns you when Windows long paths are off.

Trap 2: dependencies

A new worktree has your source files and nothing else — no node_modules, no virtual environment, no build output. An agent that immediately runs the tests will spend minutes installing, or fail.

What helps:

  • For quick tasks, link the dependencies of your main working copy into the worktree. PaneScale does this for the autopilot and Point & Fix, so checks run right away.
  • For tasks that change dependencies, let the agent install inside its own worktree — that is the point of isolation.

Trap 3: cleanup

Worktrees outlive the reason you created them. After a few weeks you have dozens, each with its own branch, and git branch becomes unreadable.

What helps:

  • Decide when you close: keep, merge or discard. PaneScale asks every time a lane’s pane closes, so the decision doesn’t pile up.
  • Use a prefix for agent branches. PaneScale uses panescale/grid/… and panescale/autopilot/…, so they are easy to tell apart from yours and easy to clean up in bulk.
  • Remove leftovers regularly. Settings → Storage lists worktrees from earlier sessions.

A note on uncommitted work

A worktree starts from a commit. Work you haven’t committed stays in your main working copy and is invisible to the agent. Usually that is what you want — it keeps your in-progress work out of the agent’s way. When it isn’t, commit first, or use a feature that copies uncommitted work on purpose, like Point & Fix or the autopilot’s Include uncommitted changes option.

The payoff

Once these three are handled, worktrees disappear into the background. You open a pane, toggle Isolated worktree, and the agent has its own desk. More in Lanes & worktrees.

More articles

Five ways an agent can fake a green build

Agents rarely cheat on purpose, but under pressure to make tests pass they find shortcuts. Here is what to look for — and what PaneScale flags automatically.

Write tasks an agent can finish

The difference between a task that runs overnight and one that wanders is usually a single sentence — the finish line. A short template and examples.

Bypass mode: a decision table

Skipping an agent’s permission prompts saves hours — and occasionally costs a lot more. When it is reasonable, and what to put in place first.