Frictionless Worktrees with Claude Code

If you want to run multiple AI coding agents in parallel, Git Worktrees are a useful trick. They allow you to spin up isolated branches of a repository in separate directories without the overhead of stashing, rebasing, or juggling multiple clones.

However, out of the box worktrees have a point of friction: every new worktree needs the same setup of non-commited files or directories, such as dependencies, env files, and other git-ignored bits. When using worktrees yourself, it’s annoying but you can work through it. But with coding agents, this friction gets amplified and is likely to waste time and tokens while the agent trips over itself, most especially if you are trying to run multiple agents side by side

Recently I have been using Claude Code on Desktop more often. Given you can easily see all your sessions and their statuses its great for running agents in parallel (Conductor and superset.sh are similar). But the worktree setup still gets in the way, just as it does via CLI’s claude --worktree. In this post I’ve documented two small changes that make using worktrees with Claude Code much smoother, in both CLI and Desktop.

The problem

A worktree gives you a fresh directory that mirrors your repository which is perfect for isolation. However most repositories have a bunch of things you don’t want to commit that are still essential to run:

• node_modules/
• .env files
• local config files
• other generated artifacts

Copying these over manually every time is tedious, and it is easy to get wrong (especially for an agent).

The fix

Claude provides a couple of mechanisms that make this a lot smoother.

Symlink shared directories

In your Claude settings.json, you can specify symlinked directories, such as dependency directories. This means instead of reinstalling dependencies in every new worktree, you can symlink a directory like node_modules so it’s shared between them.

{
  "worktree": {
    "symlinkDirectories": ["node_modules"]
  }
}

This makes new worktrees quicker to start using, and also reduces the disk space used on your machine. If your parallel sessions require different dependency changes the symlink may cause repeated installs, however I haven’t found myself in such a situation just yet.

Auto-copy git-ignored files

If you add a .worktreeinclude file at the root of your project, you can list gitignore’d files that should be automatically copied into new worktrees.

.env
.env.*

This is ideal for things like:

• .env
• local credentials files
• runtime config

It also supports wildcards, so you can match patterns that fit your project.

What this gives you

If you are running agents in parallel, the main thing you want is reduced friction so you can manage multiple sessions. The more friction, the less you can manage.

Worktrees already solve branch isolation but the setup overhead is the part that can make spinning up a new agent session feel like an uphill struggle. With symlinked directories and .worktreeinclude, you can instantly spin up a dev server or run tests in a worktree. This avoids the hassle of an agent attempting to debug missing env vars, or the time taken to reinstall dependencies from scratch.