My tooling branch held 13,667 old screenshots, totaling about 2.88 GB. A full worktree copied that archive into each new working directory. The next task might need the source files, a template, and a few references. It still got the whole archive.
I wanted to keep the screenshots. They recorded earlier checks and could be useful again. I just did not need another copy of every one each time an agent started work.
Git already had a way to make that choice: sparse checkout.
Separate workspaces solve one problem
In Make Your AI Agent Replaceable, I wrote about giving a second agent access to the work and instructions I already owned. Once several agents can work on a project, they also need room to work without changing one another’s files.
I use Git worktrees for that. A worktree is a separate working directory attached to the same repository. Each agent can work on its own branch, with its own files on disk. The repository’s stored history is shared.
That separation matters. One agent can edit a page while another works on a document. They bring their changes together through pull requests instead of sharing a working folder.
But a normal checkout also puts the branch’s tracked files into that new directory. In my private tooling branch, that included a growing archive of screenshots from earlier visual checks.
Keep the archive in Git
Sparse checkout lets you choose which tracked files appear in a working directory. The excluded files remain in Git. You can retrieve them when you need them.
My rule was narrow: leave out the PNGs in the historical screenshot archive. Keep every other tracked file.
That kept the source, stylesheets, templates, text evidence, and reference images outside the archive available to the agent. Excluding every image, or keeping only the file being edited, would have removed useful inputs too.
This changes what gets unpacked into the working directory. It does not shrink Git’s stored history, and it does not stop an agent from retrieving an excluded file. It is a disk-space choice, not an access restriction.
Make the choice before copying the files
The order was important. Creating a full worktree and then making it sparse would still unpack the archive first. I wanted new worktrees to skip that step.
The helper we added follows this order:
- Create a new branch and worktree without checking out the files.
- Set the exclusion rule for that worktree.
- Check that the rule is active.
- Populate the working directory.
The helper itself stays in Git. An agent can retrieve that one script from an existing checkout, then run it to create its workspace. It does not need to unpack the archive to get the tool that avoids unpacking the archive.
We also had to account for settings left by earlier worktrees. Some were present but inactive. Changing the shared configuration could have activated them in other sessions. The helper confines its sparse settings to the new worktree, and the verification checked that the existing worktrees kept their settings.
If your repository only needs whole folders selected, Git’s standard directory-based sparse checkout is simpler. My exclusion targeted one file type inside an archive, and the existing configuration needed care. The useful pattern to copy is the sequence, not an unexplained command pasted into a live project.
A smaller folder still has to do the job
The September 14 check on my Mac compared the files tracked in Git with the files present in the new worktree:
- All 13,667 archive PNGs were absent from the working directory.
- All 3,991 other tracked paths were still present.
- The new working directory occupied about 220 MiB.
The PNG total, about 2.88 GB, was their combined file size. The 220 MiB figure was the measured disk use of the new worktree. It excludes the shared Git storage; it is not the size of the whole repository.
Then the check ran a real document build. The two-page PDF passed its text check and was reopened and rendered for visual review. That mattered more than the folder size: the smaller checkout still supported the work it was made for.
The fix left the archive in Git and did not delete historical worktrees. Deciding which old workspace is safe to remove is a separate task. It can contain unfinished work that never reached a commit.
Keep a way to fetch what is missing
An old screenshot may be exactly what the next task needs. The instructions tell the agent to retrieve that named file from Git into its own temporary output folder. A full checkout is also available when the task needs the complete archive.
That choice belongs beside the project’s other working instructions. Otherwise, an agent may mistake an intentionally absent file for a lost one, or recreate the full checkout out of habit.
If your agents keep making large working copies, start with an inventory. Find what is repeated, decide what the next task actually needs, and test one smaller checkout against real work.
The question is: what can stay in Git until this task needs it?