claude-cow-worktree

A git worktree is a separate
working directory backed by the same repository — a
way to have several branches checked out side by side without
re-cloning. The repository's object database and most refs are
shared; only the working directory itself
is duplicated for each worktree.

Claude Code uses worktrees to let you run multiple
sessions in parallel without their edits colliding — typically you
start one per task you want to work on at the same time,
and sub-agents can opt in to the same
isolation. Each worktree that Claude Code creates consumes a fresh
copy of every tracked file. On a 3 GB repo with five active
worktrees, that's 15 GB of disk for what is essentially the same
content five times over.

On macOS, the APFS filesystem can share data blocks between files via
copy-on-write at zero cost, through the clonefile(2)
syscall. Cloned files appear as separate inodes that diverge lazily
once written to. Stock git doesn't know about this, but a Claude Code
WorktreeCreate hook can intercept the worktree creation
and use the syscall directly.

This repo provides such a hook. With it installed, a Claude
Code-driven worktree add is byte-identical to a plain git worktree add but typically consumes only the diff between source and target
in unique disk — on a 3 GB working tree, tens of MB instead of ~3 GB.

It also includes apfs-worktree-add.py, a standalone command you can
call from bash instead of git worktree add for the common worktree
creation forms.

How it works

The hook lets stock git worktree add --no-checkout set up the new
worktree's admin dir, clonefile()s the source's working directory
into place, copies the source's index over, and lets
git reset --hard apply only the actual source-to-target diff. A
final git clean -fdx drops any untracked carry-over so the result
matches a plain git worktree add byte-for-byte. This can also be
implemented inside git itself so any git worktree add
benefits.

Install

git clone https://github.com/palmin/claude-cow-worktree.git
cd claude-cow-worktree
./install.sh

install.sh merges a hook entry into ~/.claude/settings.json (and
keeps a .bak of the original on first run), pointing at the script
in the cloned repo. Re-running it is safe — duplicates are removed
and the path is updated. To remove the hook later:

./install.sh --remove

After install or removal, restart any running Claude Code session so
it re-reads settings.json.

Standalone use

apfs-worktree-add.py can be called from bash instead of
git worktree add for disk-efficient worktrees outside Claude Code.
Run it with --help for usage.

Caveats

• macOS-only. clonefile() is APFS-specific.
• Same APFS volume only. If the new worktree path resolves to a
  different volume, clonefile() returns EXDEV and the hook fails.
  This is rarely an issue because Claude Code creates worktrees
  inside the source repo's .claude/worktrees/ directory by default.
• .gitattributes divergence. A blob's working-tree
  representation can depend on filter rules (LFS, text=auto, ident,
  smudge filters, etc.). For files whose blob OID is the same in
  source and target, this hook preserves the source's representation
  rather than re-applying target's filters — the same semantic as
  git checkout between branches, not the "always re-filter"
  semantic of plain git worktree add. If you rely on per-branch
  filter divergence, run git add --renormalize . in the new
  worktree, or skip the hook for those branches.
• Hashes the working tree once. git update-index --refresh
  reads every tracked file to verify content matches the index's
  recorded OID. On a 3 GB tree this dominates wall time (~1–2 s on
  cold cache, well under a second once the FS cache is warm); cost
  scales roughly linearly with tracked-file size.
• AI-assisted, human-reviewed. This work was drafted with help
  from Claude Code and reviewed with human eyes before publishing.
  Bugs are certainly possible — please open an issue if you spot one.
  Remember that LLMs will let you down the moment you start trusting
  them.

About me

I'm Anders Borum, making developer
tools for iOS and Mac, most notably Working Copy,
the full-featured Git client for iOS putting your
side-projects in your side pocket where they belong.