Claude Code Git Worktree
> AI content disclosure: AI helped organize the troubleshooting sequence; commands and cleanup behavior were checked against the official Claude Code worktree guide.
Further reading: Compare Claude Code subagents
A Claude Code worktree gives a session its own working directory and branch while sharing repository history with the main checkout. The separation prevents two sessions from changing the same physical files, which makes parallel coding safer without cloning the repository repeatedly.
What Is Git Worktree and Why Claude Code Uses It
Git worktree is a native Git feature, not an Anthropic-specific version-control system. Claude Code builds on it for isolated sessions. File isolation and agent orchestration solve different problems: a worktree separates working state, while a subagent or agent team controls who performs and coordinates tasks.
The Claude Code desktop app creates a worktree for each new session automatically. In the CLI, use --worktree or -w. Add .claude/worktrees/ to .gitignore so generated worktree directories do not appear as untracked content in the main checkout.
Setting Up Worktrees for Parallel Claude Tasks
Start two isolated sessions from the repository:
~~~bash claude --worktree feature-auth claude --worktree bugfix-123 ~~~
By default, named worktrees appear under .claude/worktrees/ on branches such as worktree-feature-auth. If you omit a name, Claude generates one. Run Claude once in a directory and accept workspace trust before using --worktree there; otherwise non-interactive startup can fail.
Untracked, gitignored files such as .env are not part of a fresh checkout. A .worktreeinclude file can copy selected gitignored files into Claude-created worktrees. Keep secrets narrow and never use this as a reason to commit credentials.
Branching Strategy for Multi-Agent Worktrees
Current Claude Code worktrees branch from the repository's default remote branch by default, producing a clean base. Set worktree.baseRef to head when new worktrees must include local, unpushed commits. The setting accepts the documented values fresh or head, not an arbitrary branch name.
Assign one coherent outcome per worktree and keep commits small. Avoid having two worktrees redesign the same interface unless you deliberately want competing implementations. Before integration, fetch the latest base, run tests in the worktree, and review the final diff. Worktrees prevent live file collisions; they do not prevent merge or rebase conflicts later.
Common Worktree Errors and Fixes
| Symptom | Likely cause | Safe response |
|---|---|---|
| Trust error on startup | directory trust not accepted | run claude interactively once in the repository |
| Missing environment file | file is untracked or ignored | add a narrow .worktreeinclude entry or configure it manually |
| Branch already checked out | Git allows one checked-out worktree per branch | create a new branch or use the existing worktree |
| Worktree will not remove | uncommitted files or new commits exist | inspect status, preserve wanted work, then remove deliberately |
| Dependencies missing | worktree is a fresh working directory | install dependencies or use supported shared-cache settings |
Non-interactive sessions created with -p are not cleaned up through an exit prompt. Remove them explicitly with git worktree remove after preserving any results.
Worktree vs Subagents: When to Use Which
Use a worktree when concurrent work may edit overlapping files or needs independent branches. Use a subagent when the parent conversation should delegate a bounded investigation and receive a summary. Combine them by configuring an editing subagent with worktree isolation. For large coordinated teams, review agent-team behavior separately rather than assuming worktrees provide messaging or task coordination.
In Verdent
Verdent uses git worktrees as the foundation for separate Workspaces. The product adds a visual workspace lifecycle, parallel task management, change review, synchronization, and rebasing controls. Multiple tasks in one Verdent workspace still share files, so tasks likely to touch the same code should be placed in separate workspaces. That product layer goes beyond raw worktree creation without changing Git's underlying conflict rules.
Sources: Claude Code worktrees, Git worktree documentation, Verdent core concepts.
Frequently Asked Questions
Does Claude Code create git worktrees automatically?
The desktop app creates one for each new session. In the CLI, pass --worktree or -w to create an isolated worktree.
Do Claude Code worktrees share git history?
Yes. They share the repository history and remote while maintaining separate working directories, branches, and file state.
Why is my .env file missing from a worktree?
Untracked and gitignored files are absent from a fresh checkout. Configure them deliberately, such as with a narrow .worktreeinclude rule.
Do worktrees eliminate merge conflicts?
No. They prevent sessions from editing the same physical files, but conflicting changes can still surface when branches are merged or rebased.
Run Claude Code tasks in Verdent workspaces
Use Verdent workspaces to separate parallel coding tasks on top of git worktrees, then review, sync, and rebase changes with clearer controls.