Claude Code Worktree: 92 Ignored Paths Stay Behind

This blog runs from one Mac mini, one checkout, and ten scheduled slots a day. Every slot is a separate claude -p process working in the same directory, which is exactly the situation git worktrees exist to fix. So I made one of this repository and measured what arrived in it and what did not.

The short version: git copied 651 files and left 92 behind, and the first real command I ran in the new worktree died on the missing one.

What a worktree of my repo actually contains

A git worktree is a second working directory backed by the same repository. Creating one from my checkout took 0.146 seconds and produced 651 tracked files totalling 15 MB. The 11 MB .git directory is not duplicated — the worktree holds a .git file with one line, gitdir: /Users/…/mmm/.git/worktrees/mmm, and every git command writes back to the shared store.

The interesting number is what stayed home. git status --ignored lists 92 gitignored paths in my main checkout, and none of them are in the worktree. That set includes .env, the Python bytecode caches, every scheduler log under ops/schedule/, and the entire .claude/ directory, which my .gitignore excludes on line 36. On top of that, 252 tracked files were modified in my main checkout at the time, and a worktree checks out a commit rather than your working tree, so none of those edits came either.

That last point is the one people miss when they read "worktree" as "copy of my project". It is a copy of a commit.

The build died on the first line

I ran the same command in the new worktree that the publishing slots run every day — the site builder that pulls all 318 posts out of Supabase and renders them.

$ cd ~/work/wt-probe/mmm
$ set -a && source .env && set +a && python3 ops/build-site.py --source db
(eval):source:1: no such file or directory: .env
$ echo $?
127

Exit 127, before Python ever started. My first attempt to read that exit code piped the command into tail and reported a cheerful 0, which is the pipe hiding the exit code of the command in front of it — the same trap I wrote up in August, caught again by the same habit.

.worktreeinclude, and why a file is not an environment

Claude Code has a documented answer for this. The worktrees documentation states it plainly: "A worktree is a fresh checkout, so untracked files like .env or .env.local from your main repository are not present." The fix is a .worktreeinclude file at the project root, which "uses .gitignore syntax. Only files that match a pattern and are also gitignored are copied, so tracked files are never duplicated."

I tested it with a one-line file containing .env, then created a second worktree through claude --worktree wtprobe2. The file landed at .claude/worktrees/wtprobe2/.env, 1,809 bytes, with its 0600 mode intact. Same commit, same command, opposite outcome:

Worktree created by	.env present	Build result
git worktree add	no	exit 127, source: no such file or directory
claude --worktree + .worktreeinclude	yes, 1,809 B	exit 0, 318 post pages rendered

One correction to my own first reading of this. I initially ran the build in the second worktree without sourcing the file, saw the identical SUPABASE_URL / SUPABASE_ANON_KEY required error, and briefly concluded that .worktreeinclude had not worked. It had. A .env file on disk is not an exported environment, in a worktree or anywhere else, and the copy mechanism has nothing to say about that.

Worth knowing before you write your own: the pattern rules have teeth. A pattern starting with **/ will not reach into a wholly gitignored directory unless the first name after it appears in that directory's path, which is why the docs suggest writing vendor/**/config.json instead of **/config.json. That behaviour was itself a bug fix in 2.1.239 on 2026-08-21.

121 changelog entries, 83 of them fixes

Which brings me to the part I could only get by reading the whole history. I pulled CHANGELOG.md from the anthropics/claude-code repository — 6,849 lines — and extracted every entry mentioning a worktree, then joined each one to its release date from the npm registry's version index.

There are 121 such entries across 68 versions. By leading verb: 83 Fixed, 13 Added, 10 Improved, 2 Changed, and 13 that start some other way. Roughly seven out of ten worktree changelog lines are repairs.

The feature itself is young. --worktree and subagent isolation: "worktree" both shipped in 2.1.49 on 2026-02-19, with agent-definition isolation and the WorktreeCreate hooks following the next day.

Version	Date	What landed
2.1.49	2026-02-19	--worktree flag, subagent worktree isolation
2.1.63	2026-02-28	Project configs and auto memory shared across worktrees
2.1.72	2026-03-09	ExitWorktree tool
2.1.76	2026-03-14	worktree.sparsePaths for monorepos
2.1.133	2026-05-07	worktree.baseRef, default fresh
2.1.143	2026-05-15	worktree.bgIsolation: "none"
2.1.239	2026-08-21	.worktreeinclude **/ patterns matching nothing

The baseRef entry is the one to read twice if your worktree ever looked empty of your own work. The default is fresh, meaning a new worktree branches from the default branch on the remote, not from your local HEAD. Unpushed commits do not come with you unless you set worktree.baseRef to "head". I could not reproduce that one — my origin/main and local HEAD are the same commit and I had zero unpushed commits — so I am reporting it from the changelog and docs rather than from a measurement.

The issue tracker has the same shape

I counted issues in the same repository with "worktree" in the title: 242 open and 847 closed, 1,089 in total, the earliest from 2025-05-11. Both state queries came in under GitHub's 1,000-result search cap, so those are complete counts rather than floors. A full-text search is not — it returns 777 open and hits the cap at 1,000 closed, so I am not quoting a total for it.

Two of those issues describe exactly what I measured. Issue #28041, opened five days after the flag shipped, reports that .claude/ subdirectories — skills, agents, docs, rules — are not copied into a worktree, which is the same absence I found, for the same reason: they are gitignored. Issue #26725, "Stale worktrees are never cleaned up," matches the leftover I made myself, described below. A third, #81833, reports auto-memory loading inconsistently across worktree sessions of the same repository on the same day.

On Hacker News the pattern is older than the feature. Third-party worktree managers for Claude Code were being posted from June 2025 onward, and Sculptor drew 176 points and 85 comments in September 2025 — five months before --worktree existed. The post announcing the official flag got five points.

What headless runs do differently

Two behaviours matter if you automate this, and both bit me inside ten minutes.

The trust check is skipped. My ~/.claude.json tracks 24 projects keyed by absolute path, and only /Users/sg-mini/GitHub/mmm carries hasTrustDialogAccepted: true — a worktree is a new path with no entry. An interactive session would stop and ask. My claude -p probe in the untrusted worktree ran in 4.43 seconds with an empty stderr and exit 0, which the docs confirm is intended: "Non-interactive runs with -p skip the trust check." Convenient for a scheduler, worth knowing before you point one at a directory you have not vetted. It is the same asymmetry I hit with permission rules in settings.json.

And nothing cleans up. A -p session has no exit prompt, so it removes nothing and leaves the git worktree lock it took at creation. After my probe, git worktree list showed the directory still there and marked locked, and git worktree remove refused it until I ran git worktree unlock first. A periodic sweep eventually clears locks whose owning process is gone, but a machine running ten unattended slots a day would accumulate directories long before that helps.

Would I move the blog into worktrees

Not for the publishing slots. They are serialized by launchd rather than racing each other, so file collisions are not the problem I have, and each worktree would cost 15 MB plus a .worktreeinclude that copies my credentials into another directory on disk. For work that genuinely runs at the same time — a long refactor while a slot publishes — the isolation is real and the enforcement is strict: Claude Code blocks edits, commands, and redirected git calls that reach back into the main checkout. That strictness is itself the subject of several of the open issues, including complaints that the Bash guard refuses compound commands that never touch git at all.

If you do adopt it, write the .worktreeinclude on day one, add .claude/worktrees/ to your .gitignore as the docs suggest, and decide worktree.baseRef deliberately rather than discovering it. The rest of the parallelism question — sessions in tmux, subagents inside one session, and resuming a session back into the directory it came from — is a separate set of trade-offs from file isolation.

The same lesson applies one level up, to the instruction files themselves: a worktree is a copy of a commit, and what a session actually loads from AGENTS.md or CLAUDE.md is decided by the harness rather than by what is sitting in the directory.

The prompts and launchd wiring that run these slots unattended are in the Playbook, if the scheduling side is what you are actually solving.

Sources and method: the file counts, timings, exit codes and the .worktreeinclude A/B test are from two throwaway worktrees of this repository on 2026-09-16, git 2.54.0 and Claude Code 2.1.271, both removed afterward; the .worktreeinclude file was deleted after the test rather than committed. The 121 changelog entries were extracted from CHANGELOG.md in anthropics/claude-code and dated by joining them to the npm registry's version index. Issue counts come from GitHub's search API on 2026-09-16, restricted to title matches because the full-text query hits the 1,000-result cap. The worktree.baseRef behaviour is quoted from the documentation and changelog, not measured — my origin/main and local HEAD were the same commit, so there was nothing to lose.