worktree
Manage Git worktrees for parallel development. Use when creating, listing, or removing worktrees, or when discussing parallel module development.
name: worktree description: Manage Git worktrees for parallel development. Use when creating, listing, or removing worktrees, or when discussing parallel module development. allowed-tools: Bash, Read
Git Worktree Management
Manages git worktrees for parallel feature development on different branches.
Key Principle: 1 Worktree = 1 Branch = 1 PR
Each worktree maps to exactly:
- ONE feature branch
- ONE pull request
- ONE GitHub issue
This ensures clear ownership, easy cleanup, and traceable history.
When to Use Worktrees
- Working on multiple features simultaneously
- Need to context-switch without stashing
- Running long tests while developing elsewhere
- Reviewing PRs while maintaining current work
- Delegating work to subagents
Proactive Worktree Creation
Claude and subagents should AUTOMATICALLY create worktrees (without waiting for user request) when:
- Starting work that may conflict with other ongoing tasks
- Multiple parallel implementations are in progress
- Delegating any work to subagents
Default behavior: When in doubt, create a worktree. It's safer to have isolated work than to risk conflicts.
Create Worktree
For Feature Development
git worktree add ../auto-invoice-collector-{name} -b feature/{issue}-{description}
Example:
git worktree add ../auto-invoice-collector-feature-123 -b feature/123-new-feature
cd ../auto-invoice-collector-feature-123
npm install
For Phase Development
git worktree add ../auto-invoice-collector-phase5 -b develop/phase5
List Active Worktrees
git worktree list
Remove Worktree
After merging, remove the worktree:
git worktree remove ../auto-invoice-collector-{name}
Force remove if needed:
git worktree remove --force ../auto-invoice-collector-{name}
Prune Stale Worktrees
Clean up worktrees pointing to deleted directories:
git worktree prune
Directory Naming Convention
Include feature/responsibility in worktree name for clarity:
| Purpose | Directory | Branch Pattern |
|---|---|---|
| Feature | -wt-{feature} |
feature/{issue}-{desc} |
| Phase | -phase{N} |
develop/phase{N} |
| Hotfix | -wt-fix-{issue} |
fix/{issue}-{desc} |
| Module | -wt-{module} |
feature/{module}-{desc} |
Examples:
-wt-authfor authentication feature-wt-ocr-fixfor OCR bug fix-wt-journal-uifor journal UI work
Pattern: ../auto-invoice-collector-wt-{feature-short-name}
Important Notes
- Each worktree has independent working directory and index
- Branches cannot be checked out in multiple worktrees
- Run
npm installin each new worktree - Worktrees share the same
.gitrepository
Subagent Workflow
When delegating to subagents:
Create worktree for the subagent's work:
git worktree add ../auto-invoice-collector-subagent-task -b feature/123-taskProvide the worktree path to the subagent
Subagent works in isolation
Review changes and merge from main repo:
git worktree remove ../auto-invoice-collector-subagent-task
Post-Merge Cleanup (MANDATORY)
After PR merge, ALWAYS remove the worktree:
# From main repo directory
git worktree remove ../auto-invoice-collector-wt-{name}
# Verify removal
git worktree list
NEVER leave stale worktrees. The /merge skill handles this automatically, but if merging manually, cleanup is required.