Worktree creation refused for lack of disk space with ~20x the required space free

Summary

Creating a worktree is refused with "Not enough free disk space to set up a worktree" even when free space exceeds the actual requirement by roughly 20×. The check appears to be sized against the repository directory rather than against what a worktree actually writes, which makes it fire hardest on exactly the repositories where worktrees are most useful — large ones.

Environment

• Claude Code 2.1.159, macOS 15 (Darwin 25.5.0), APFS
• Repository directory: 70 GB total
• .git/objects: 21 GB (7 packs, 49 587 objects — large binary blobs in history)
• gitignored data and environments: ~45 GB (.pixi, generated data, page images)
• tracked files: 3.8 GB

What happens

The error appeared at 25 GB free. I freed 21 GB (removing eight worktrees whose branches were already merged, plus one finished agent worktree). At 46 GB free the error was identical.

Measurement

A worktree was then created manually from the same repository, at the same moment, on the same volume:

$ git worktree add --detach /tmp/wt-test HEAD
Updating files: 100% (4847/4847), done.

size on disk:        2.3 GB
actually consumed:   2.27 GB   (measured with df before/after)

So the real requirement is 2.27 GB against 46 GB available. git worktree add had no objection — only the pre-flight check does.

Why I think it sizes against the repo directory

The two data points fit that rule exactly and no other I could find:

| free space | repo dir | result |
|---|---|---|
| 25 GB | 77 GB | refused |
| 46 GB | 70 GB | refused |

Both times free < repo dir. If the threshold were the actual cost (2.27 GB) or even the tracked size (3.8 GB), both attempts would have succeeded.

I could not confirm this from the code — the string "Not enough free disk space" does not appear in the CLI binary at ~/.local/share/claude/versions/2.1.159, so the check seems to live in the app layer.

Why this matters

A worktree shares .git with the main checkout and does not copy gitignored files, so its cost is the size of the tracked working tree — here 3.8 GB out of 70 GB, or 5%. Sizing against the whole directory overstates the requirement by a factor of ~18 in this repository, and the overstatement grows with .git size and with gitignored data. Repositories with large histories or large local datasets are precisely the ones where developers reach for worktrees instead of switching branches in place.

There is also a compounding effect: agent worktrees are created under <repo>/.claude/worktrees/, i.e. inside the directory being measured. Each one left behind after a task finishes makes the next worktree look more expensive to create. One leftover in my case held 6.6 GB on a branch that had already been merged.

Suggested fix

Size the check against what is actually written — the tracked working tree (git ls-files size, or the checkout size reported by git) — rather than the repository directory. Excluding .git alone would already remove most of the error here; excluding gitignored paths removes the rest.

If a conservative margin is wanted, a multiple of the tracked size would still be far below the current threshold and would stop rejecting cases with 20× headroom.

Workaround

git worktree add <path> -b <branch> works normally, and the resulting worktree can be used as usual.