Git Sparse Checkout Per Worktree for AI Agents
Prepared and checked using AI. Sources are linked in the article.
To use git sparse checkout per worktree, give each agent its own worktree and branch, then run git sparse-checkout set inside each worktree with the directories that agent needs. Git worktrees have separate working directories and indexes, while sparse checkout stores its directory selection per worktree. One agent can see the API and its shared package; another can see the web app and that same package.
Choose each agent’s directory set
For example, suppose a monorepo has apps/api, apps/web, packages/shared, and infra. The API agent needs apps/api and packages/shared; the web agent needs apps/web and packages/shared. List dependencies an agent must read, edit, or build against, even when another agent owns the main changes there.
| Agent task | Directories to include | Reason |
|---|---|---|
| API endpoint | apps/api packages/shared | Work on the service and its shared types. |
| Web screen | apps/web packages/shared | Work on the interface and the same types. |
Use directory paths relative to the repository root. The default cone mode includes every file beneath a selected directory. It also includes files directly in the repository root and directly in each selected directory’s ancestors. Selecting apps/api, for instance, does not mean the worktree contains only apps/api: root files and files directly under apps remain visible. Check the actual directory layout before making an agent’s context smaller.
Sparse checkout is a useful way to narrow the files on disk, but it does not assign ownership of shared files. If both agents can edit packages/shared, give them separate tasks and review their changes together. For planning that boundary, see how to split work for parallel agents.
Create a branch and sparse checkout for each agent
Run these commands from the main monorepo worktree. The sibling worktree paths and branch names below are examples; choose paths outside the working tree you are currently using.
git worktree add -b agent/api ../monorepo-api HEAD
git worktree add -b agent/web ../monorepo-web HEAD
git -C ../monorepo-api sparse-checkout set --cone apps/api packages/shared
git -C ../monorepo-web sparse-checkout set --cone apps/web packages/sharedgit worktree add -b creates a new branch at the specified starting commit. Here, both branches start at HEAD, so the agents begin from the same snapshot. The ordinary worktree add command checks out that snapshot before the sparse settings are applied; set then updates each working directory to match its own selection. Start the relevant agent CLI from its assigned worktree after these commands finish.
Use a distinct branch for each agent. Git normally refuses to check out a branch that another worktree already has checked out. Separate branches also give each agent a clear diff to review and integrate. For the wider worktree workflow, see Git worktrees for AI agents.
Verify that the selections stay separate
Inspect the directory rules from each worktree rather than assuming a command run in one directory changed both:
git -C ../monorepo-api sparse-checkout list
git -C ../monorepo-web sparse-checkout list
git worktree listThe first two commands should list different app directories and the shared package. git worktree list identifies each worktree and its branch; it does not show sparse directory rules. If an agent needs an unexpected file, check whether that file is included through a root or ancestor directory before widening the selection.
Git’s extensions.worktreeConfig setting lets each worktree keep its own configuration. git sparse-checkout set enables that extension when needed and writes sparse settings for the current worktree. You can inspect where a setting came from:
git -C ../monorepo-api config --show-origin --get core.sparseCheckout
git -C ../monorepo-web config --show-origin --get core.sparseCheckoutExpect the effective value to be true for both and the worktree-specific configuration to take precedence. Avoid setting core.sparseCheckout in the repository’s shared config for a mixed setup where some worktrees should remain full. If this is an older repository with shared core.worktree or core.bare settings, review Git’s migration requirements before enabling worktree-specific config. Older Git versions may also reject a repository using this extension.
Widen or replace an agent’s view
When a task expands, use add to include another directory without replacing the current set:
git -C ../monorepo-api sparse-checkout add infraIf the API agent changes focus entirely, use set with the complete new list. set replaces the selection; leaving packages/shared out of the command removes it from that agent’s sparse definition:
git -C ../monorepo-api sparse-checkout set --cone apps/api infraTo restore every tracked file in one worktree, run git -C ../monorepo-api sparse-checkout disable. That changes the API worktree’s working directory, not the web worktree’s selection. If a merge or rebase brings files outside the selected directories into view, resolve any conflicts or changes first and then use git -C ../monorepo-api sparse-checkout reapply to apply the existing rules again.
Change rules cautiously once an agent has generated files. Git notes that changing a cone-mode selection can remove ignored files in a directory that no longer contains tracked or non-ignored untracked files. Keep a needed build directory in the selection, or preserve its contents before shrinking that worktree.
Account for builds, indexes, and downloads
Begin with the directories needed for the agent’s task and its local build or test command. A build that reads a package outside the selection will need that package included, even if the agent should not edit it. Add the dependency with sparse-checkout add, rerun the relevant command, and keep the agent’s edit scope explicit in its task instructions.
Cone mode is the default and accepts directories. Git discourages --no-cone, which accepts patterns, because of its scaling and compatibility drawbacks. If you need one file inside a deep directory, selecting that directory is usually the simpler trade-off; it may expose more nearby files than the task strictly needs.
A sparse index is optional: git sparse-checkout set --cone --sparse-index ... can reduce index size and help commands such as git status or git add. Git labels this feature experimental and warns that some external tools or older Git versions may not understand its index format. Leave the default index format in place unless the repository and agent tooling benefit from the option.
Sparse checkout controls which tracked files appear in a working directory. If the objective also includes reducing objects transferred during an initial clone, Git’s clone --filter=blob:none defers file contents until needed. That is a separate clone choice. A linked worktree uses the repository you already have, so adding more sparse worktrees does not apply a new clone filter to it.
Review and retire agent worktrees
Files omitted by sparse checkout are still tracked; their absence is not a deletion to commit. Git also keeps git commit -a from recording out-of-selection paths as deleted. Review each agent’s actual changes and any shared-package edits before merging branches. When an agent’s work is safely retained, git worktree remove ../monorepo-api removes a clean linked worktree; Git refuses to remove an unclean one without force.
Because an agent can run sparse-checkout add or disable, treat the selection as a workspace convenience rather than an access boundary. It reduces the files an agent normally sees and navigates, while the worktrees still belong to one repository.
Where Parallel Code fits
Parallel Code is our free, open-source desktop app for macOS and Linux that runs several AI coding agents in parallel, each in its own Git worktree. You can set sparse checkout separately inside each agent’s worktree using the Git commands above, then use Parallel Code’s diff-first review surface to examine the results.
Frequently asked questions
Does sparse checkout in one worktree change another agent’s files?
Running git sparse-checkout set in one worktree stores that selection for that worktree. Check each agent’s rules with git -C <worktree-path> sparse-checkout list if the visible directories are unexpected.
Can two agents include the same shared package?
Yes. Include that directory in both sparse selections when both tasks need it. The worktrees have separate working files, but changes to the same package still need review when you bring the branches together.
Does sparse checkout stop an agent from accessing other code?
No. It selects which tracked files appear in that worktree; the agent can change the selection with Git commands. Use separate access controls if a directory must be unavailable to an agent.
Will sparse checkout make a monorepo clone smaller?
Sparse checkout reduces the files populated in the working directory. For a new clone, --filter=blob:none is the separate option for deferring file-content downloads; adding a sparse worktree to an existing clone does not retroactively change what was fetched.