Detailed Analysis
Claude Code's worktree feature provides a mechanism for running fully isolated parallel development sessions by leveraging Git's native worktree functionality, which allows multiple working directories to share the same repository history and remote while maintaining completely separate file states. When a developer invokes `claude --worktree <name>`, Claude Code automatically creates a new directory under `.claude/worktrees/<name>/` and checks out a fresh branch named `worktree-<name>`, derived by default from `origin/HEAD`. This design ensures that simultaneous sessions — one building a feature, another patching a bug — never produce file-level conflicts, a persistent pain point in traditional multi-terminal development workflows. The desktop application extends this behavior further by creating a worktree automatically for every new session, removing the burden of manual setup entirely.
The feature addresses a nuanced practical challenge: while worktrees start as clean checkouts aligned with the remote, real-world projects routinely depend on untracked files like `.env` or `config/secrets.json` that are deliberately excluded from version control. Claude Code solves this by honoring a `.worktreeinclude` file at the project root, which uses `.gitignore` syntax to specify gitignored files that should be copied into each new worktree. The system applies this copying logic uniformly across CLI worktrees, subagent worktrees, and desktop parallel sessions, ensuring consistent environments without requiring manual file duplication. Developers can also configure the `worktree.baseRef` setting to branch from local `HEAD` rather than the remote, which becomes essential when subagents need to operate on in-progress work that has not yet been pushed upstream.
The subagent integration is a particularly significant architectural dimension. Claude Code allows individual subagents to run inside their own worktrees — either by user instruction or via an `isolation: worktree` frontmatter setting on custom subagents — enabling parallel AI-driven code changes that are physically separated at the file-system level. This prevents a class of race conditions where two subagents independently modify the same file, a problem that becomes acute as multi-agent orchestration grows more sophisticated. Temporary subagent worktrees are cleaned up automatically when they exit without changes, while worktrees containing commits or modifications prompt the user to decide whether to preserve or discard them, preserving human oversight over what survives the session.
The broader trajectory reflected in this documentation is the normalization of agent-native development tooling — infrastructure designed not just for human developers running multiple terminals, but for orchestrating teams of AI agents operating concurrently on a shared codebase. The `WorktreeCreate` and `WorktreeRemove` hooks signal that Anthropic is building extensibility into the system at the isolation layer itself, allowing organizations using SVN, Perforce, Mercurial, or proprietary systems to substitute their own creation and cleanup logic. This positions Claude Code as a platform-level tool rather than a Git-specific workflow aid, suggesting that the worktree abstraction is intended to generalize across enterprise version control environments as agentic coding workflows mature and diversify.
Read original article →