Configure Worktree Symlinks and Sparse Checkout for Monorepos

If you use --worktree for parallel tasks in a large monorepo, each worktree gets a full copy of your repo by default. That means duplicating node_modules, build caches, and every package you don't care about. Two settings fix this.

Symlink large directories instead of copying them:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache", "vendor"]
  }
}

This creates symlinks from the worktree back to the main repo for the listed directories, saving disk space and speeding up worktree creation.

For truly massive monorepos, use sparse checkout so only the packages you need get written to disk:

{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils", "configs"]
  }
}

This uses git's sparse-checkout in cone mode. Only the listed directories are checked out in the worktree, which is dramatically faster when your repo has hundreds of packages.

You can combine both settings. Symlink the heavy shared directories and sparse-checkout only the code you're working on. Add these to your project's .claude/settings.json so everyone on the team benefits.

Stop cloning the whole monorepo into every worktree. Symlink and sparse-checkout instead.

via Claude Code Docs — Settings