Sparse Worktrees for Monorepos
In large monorepos, full worktree checkouts include files the agent will never touch. Sparse worktrees limit the checkout to only the paths you specify — faster startup, less disk usage, and sharper Glob/Grep results.
Quick Reference
- →worktree.sparsePaths in .claude/settings.json restricts worktree checkout to specific paths
- →Uses git sparse-checkout (cone mode) under the hood
- →10× faster startup on large monorepos — fewer files to write to disk
- →Significantly reduced disk usage — each worktree is only the subset you need
- →Glob and Grep are faster — fewer files to search means fewer false positives
- →Files outside sparsePaths are not checked out — tasks needing those files will fail to read them
- →Can combine with worktree.symlinkDirectories for shared assets
- →Introduced in Claude Code v2.1.76
The Monorepo Problem
Git worktrees check out the entire repository by default. In a small repo with hundreds of files, this is instant. In a monorepo with 50 packages and 500,000 files, each worktree creation means writing hundreds of megabytes to disk — and every Glob or Grep call searches all 500,000 files.
When an agent is working on packages/api, it does not need packages/mobile, packages/docs, packages/design-system, or any of the other 46 packages. But without sparse checkout, all of them are materialized in the worktree anyway.
The worktree.sparsePaths configuration option was introduced in Claude Code v2.1.76. If you are on an earlier version, upgrade to access sparse worktree support.