Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
Git worktrees create isolated workspaces sharing same repo, work on multiple branches simultaneously without switching.
Core principle: Consistent naming + safety verification = reliable isolation.
Always use this format:
Directory: .claude/worktrees/{type}/{description}
Branch: {type}/{description}
feat, fix, chore, docs, refactor, test, ci, perfworktree- prefix. No + separator.Examples:
git worktree add .claude/worktrees/feat/slack-notifications -b feat/slack-notifications
git worktree add .claude/worktrees/fix/auth-token-expiry -b fix/auth-token-expiry
git worktree add .claude/worktrees/chore/update-dependencies -b chore/update-dependencies
git worktree add .claude/worktrees/ci/add-lint-step -b ci/add-lint-step
Always use .claude/worktrees/ — already in .gitignore, no verification needed.
Never use .worktrees/ or worktrees/ — those are legacy locations.
Pick type from: feat fix chore docs refactor test ci perf
Make description kebab-case and concise.
git worktree add .claude/worktrees/{type}/{description} -b {type}/{description}
Auto-detect and run:
if [ -f package.json ]; then bun install; fi
if [ -f Cargo.toml ]; then cargo build; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
if [ -f go.mod ]; then go mod download; fi
Run tests. Tests fail: report, ask whether to proceed. Tests pass: report ready.
Worktree ready at .claude/worktrees/{type}/{description}
Branch: {type}/{description}
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
| Situation | Action |
|---|---|
| New worktree | .claude/worktrees/{type}/{description} |
| Branch name | {type}/{description} (matches folder, no prefix) |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
| Mistake | Fix |
|---|---|
worktree- prefix on branch | Drop prefix, use {type}/{description} |
+ separator in name | Use / separator: {type}/{description} |
Using .worktrees/ dir | Use .claude/worktrees/ |
| Flat name without type | Always include type prefix |
| Proceed with failing tests | Report failures, get explicit permission |
Never:
.worktrees/ or worktrees/ (legacy, non-standard)worktree- prefix on branch names+ as separator (legacy style)Always:
.claude/worktrees/{type}/{description} for dir{type}/{description}Called by:
Pairs with: