Git Worktrees — What They Are and How Claude Code Uses Them
Git worktrees let you have multiple branches checked out simultaneously in separate directories — no stashing, no switching. Claude Code wraps this capability to give each session and subagent its own isolated workspace.
Quick Reference
- →A worktree is a separate working directory linked to the same git repo, on its own branch
- →Multiple branches active simultaneously — each in a different directory
- →No stash, no switch: the main tree is untouched while you work in a worktree
- →Claude Code stores worktrees at .claude/worktrees/{name}/
- →Each worktree has its own file state, branch, and Claude Code session
- →Shared across all worktrees: git history, all branches, CLAUDE.md, settings.json
- →Auto-cleanup: worktrees with no commits are removed when the session exits
- →Crashed sessions leave stale worktrees — Claude Code cleans them up periodically
What Git Worktrees Are
A git worktree is a separate working directory that is linked to the same repository as your main checkout. Each worktree is checked out on its own branch. Changes made in one worktree do not appear in another until they are committed and merged.
Normally, a git repository has exactly one working directory. When you want to work on a different branch, you have to stash your changes, switch branches, do the work, and switch back. Worktrees eliminate this. You can have main, feature/auth, and hotfix/login all checked out simultaneously — each in its own directory — and switch between them by changing directories, not branches.