Worktree isolation: 3 gaps — stale cleanup, venv/env missing, build cache collisions

Summary

I recently published a deep-dive article on Claude Code's worktree isolation after researching the implementation and real-world usage: https://my.feishu.cn/docx/O1O0daR6SoSiKsxksiecFjk7nKc

The model is well-designed at the conceptual level (git-worktree-backed per-agent filesystem views), but three gaps keep surfacing in practice:

1. Stale worktrees never garbage-collected (#26725)

17 👍, 6 comments. Users report 15+ orphaned worktrees from a single session, nested worktrees inside other worktrees, and no startup-time cleanup. Manual bash loops are the only mitigation.

2. .venv / .env / gitignored dev files not available in worktrees (#27744)

24 👍, 5 comments. Because git worktree add only checks out tracked files, Python agents can't run pytest/mypy, and Node agents can't access .env.local. The proposed fix is a PostWorktreeCreate hook, but for now the workaround is manual symlinking via symlinkDirectories.

3. Build cache collisions across worktrees (no existing issue)

This is a language-ecosystem problem that git worktree isolation doesn't address: parallel agents building Rust, Python, or Node.js will still collide on shared cache directories (target/, __pycache__/, .next/). The koda project suggested per-agent env vars (CARGO_TARGET_DIR, PYTHONPYCACHEPREFIX, npm_config_cache), but Claude Code doesn't set these automatically.

Ask

Point (1) and (2) already have issues — this is to give the product team a consolidated view of the pain points from a single article. Point (3) is new to the official tracker and worth scoping separately if there's interest.