Using Git Worktrees

---

name: using-git-worktrees description: >- Use git worktrees to work on multiple branches simultaneously. Detects existing worktrees, guards against submodules, and prefers native Claude Code worktree tool over raw git.

Detection

Before creating a worktree, check if one already exists:

git worktree list

If a worktree for the target branch already exists, use it instead of creating a new one.

Guard: Submodules

If the repo uses submodules, DO NOT use git worktrees. Submodules in worktrees are fragile and error-prone. Use git stash + git checkout instead.

To check: git submodule status

Priority: Native Tool First

Prefer EnterWorktree tool over raw git worktree add:

• EnterWorktree({name: "branch-name"}) — creates worktree and switches session
• ExitWorktree({action: "keep"|"remove"}) — exits and optionally cleans up

Only use raw git worktree add if the native tool is unavailable or insufficient.

Directory Priority

Worktrees should go in .claude/worktrees/ (Claude Code convention).

When using EnterWorktree, the worktree is automatically placed there.

Cleanup

• After merging a worktree branch, remove the worktree: ExitWorktree({action: "remove"})
• If work is paused and you want to keep it: ExitWorktree({action: "keep"})
• Prune stale worktree references: git worktree prune