Git Worktree Manager

Manages the full lifecycle of git worktrees: creation, monitoring, cleanup, and maintenance.

Subcommands

Command	Alias	Description
`/worktree create <name>`	`/worktree <name>`	Create new worktree with conventional branch naming
`/worktree list`	`/worktree ls`	Show all worktrees with status and branch info
`/worktree remove <path>`	`/worktree rm`	Remove worktree + cleanup branches
`/worktree cleanup`	-	Interactive batch removal of multiple worktrees
`/worktree prune`	-	Remove stale worktree references
`/worktree lock <path>`	-	Prevent worktree from being auto-pruned
`/worktree unlock <path>`	-	Allow worktree to be pruned again

Default: No subcommand or unrecognized arg = create

When to use

Creating isolated workspace for new feature/fix
Viewing all active worktrees across a repo
Cleaning up after merging PRs
Removing abandoned/stale worktrees
Protecting important worktrees on portable storage

When not to use

Simple branch switching (use git checkout)
Temporary file exploration (use git stash or read-only)
Submodule management (different concept)

Subcommand: create

Creates new worktree in sibling directory with conventional commit branch naming.

Workflow

Get name: From args or ask user (e.g., "alerts", "fix-login")
Prompt for type: Use AskUserQuestion
- Header: "Commit type"
- Options: feat, fix, chore, docs, refactor, test, perf, ci
Construct branch: {type}/{name} (e.g., feat/alerts)
Determine path:
- Get repo name from remote/directory
- Path: ../{repo}-{type}-{name} (slashes → hyphens)
Create:
```
git worktree add -b {branch} {path}
```
Confirm: Show branch name, path, and cd command

Error handling

Branch exists → offer to use existing or suggest new name
Directory exists → warn and ask to proceed or rename
Dirty working tree → warn but allow (worktree add works regardless)

Subcommand: list

Shows all worktrees with status information.

Workflow

Run: git worktree list -v
Parse and display:
- Path
- Branch name (or "detached HEAD")
- Status flags: locked, prunable, bare
- Commit SHA (short)
Enhance (optional): For each worktree, show:
- Uncommitted changes count: git -C {path} status --porcelain | wc -l
- Ahead/behind upstream: git -C {path} rev-list --left-right --count @{u}...HEAD

Example output

Worktrees for my-project:
  /path/to/main          [main]           clean, up-to-date
  /path/to/feat-alerts   [feat/alerts]    3 uncommitted, 2 ahead
  /path/to/old-feature   [fix/old]        prunable (directory missing)

Subcommand: remove

Removes single worktree with full branch cleanup.

Workflow

Identify target: From args or show list and ask
Check status:
```
git -C {path} status --porcelain
```
- If uncommitted changes → warn and confirm force removal
Get branch name for cleanup:
```
git -C {path} branch --show-current
```

Remove worktree:

git worktree remove {path}        # clean
git worktree remove -f {path}     # if uncommitted changes
git worktree remove -ff {path}    # if locked

Delete local branch:

git branch -d {branch}    # safe (fails if unmerged)
git branch -D {branch}    # force (if user confirms)

Offer remote branch deletion (AskUserQuestion):
- Check if remote exists: git ls-remote --heads origin {branch}
- If yes, ask: "Delete remote branch too?"
- If yes: git push origin --delete {branch}
Confirm: Summarize what was removed

Safety checks

Never remove main worktree (the original repo)
Warn if branch has unpushed commits
Warn if PR is still open for this branch

Subcommand: cleanup

Interactive batch removal of multiple worktrees.

Workflow

List all worktrees: git worktree list --porcelain
Filter candidates:
- Exclude main worktree
- Flag: prunable, merged branches, old (no commits in 2+ weeks)
Present selection (AskUserQuestion with multiSelect):
- Header: "Cleanup"
- Question: "Which worktrees should be removed?"
- Options: List each non-main worktree with status
For each selected: Run remove workflow
Run prune: git worktree prune -v
Summary: Show what was cleaned up

Subcommand: prune

Removes stale worktree administrative files.

Workflow

Preview: git worktree prune -n -v
If stale entries found:
- Show what will be pruned
- Confirm with user
Prune: git worktree prune -v
Report: Show removed entries

When to use

After manually deleting worktree directories
After moving worktree without git worktree move
Periodic maintenance

Subcommand: lock / unlock

Protects worktree from automatic pruning.

Lock workflow

Identify worktree: From args or list and ask
Prompt for reason (optional):
- "Why lock this worktree?" (e.g., "portable drive", "long-running experiment")

Lock:

git worktree lock --reason "{reason}" {path}
# or without reason:
git worktree lock {path}

Confirm: Show locked status

Unlock workflow

Identify worktree: From args or list locked ones
Unlock: git worktree unlock {path}
Confirm: Show unlocked status

Validation checklist

Correct subcommand identified from args
Branch naming follows {type}/{name} convention
Worktree path is sibling directory, not nested
No uncommitted changes lost without warning
Local branch deleted only after worktree removal
Remote branch deletion is opt-in, not automatic
Main worktree protected from removal
Prune only runs after user confirmation

Examples

Example 1: Create

User: /worktree queue-alerts
Claude: [asks commit type] → User: feat
Claude: Created worktree
  Branch: feat/queue-alerts
  Path: ../my-project-feat-queue-alerts
  Run: cd ../my-project-feat-queue-alerts

Example 2: List

User: /worktree list
Claude: Worktrees for my-project:
  /Users/me/my-project              [main]           clean
  /Users/me/my-project-feat-alerts  [feat/alerts]    2 uncommitted
  /Users/me/my-project-fix-bug      [fix/bug-123]    prunable

Example 3: Remove with cleanup

User: /worktree remove ../my-project-feat-alerts
Claude: Worktree has 2 uncommitted changes. Force remove?
User: yes
Claude: [asks about remote branch deletion] → User: yes
Claude: Removed:
  - Worktree: ../my-project-feat-alerts
  - Local branch: feat/alerts
  - Remote branch: origin/feat/alerts

Example 4: Interactive cleanup

User: /worktree cleanup
Claude: [shows multiselect with 3 worktrees]
User: [selects 2]
Claude: Removed 2 worktrees, pruned 1 stale entry
  - feat/old-feature (merged)
  - fix/abandoned (no remote)

Notes

Worktrees share git objects but have separate working directories
Each worktree can have different branch checked out simultaneously
Locked worktrees survive git gc and won't be auto-pruned
Use git worktree move to relocate (not manual mv)
See WORKFLOWS.md for detailed step-by-step procedures

Evaluation Prompts

Test 1: Activation - create (should trigger)

User: /worktree new-dashboard
Expected: Skill activates, asks for commit type, creates worktree

Test 2: Activation - list (should trigger)

User: /worktree list
Expected: Skill activates, runs git worktree list, shows formatted output

Test 3: Activation - cleanup (should trigger)

User: /worktree cleanup
Expected: Skill activates, lists worktrees with multiselect, processes removals

Test 4: Activation - natural language (should trigger)

User: I need to clean up my old worktrees
Expected: Skill activates with cleanup subcommand context

Test 5: Non-activation (should NOT trigger)

User: How do I switch to a different branch?
Expected: Normal response about git checkout/switch, NOT worktree skill

Test 6: Non-activation (should NOT trigger)

User: Delete the feature-x branch
Expected: Normal git branch -d advice, NOT worktree removal

Test 7: Edge case - remove main worktree

User: /worktree remove .
Expected: Skill refuses with clear error "Cannot remove main worktree"

Test 8: Edge case - remove with uncommitted changes

User: /worktree remove ../project-feat-wip
Context: Worktree has uncommitted changes
Expected: Warning shown, asks for confirmation before force removal

Test 9: Edge case - no worktrees to cleanup

User: /worktree cleanup
Context: Only main worktree exists
Expected: "No worktrees available for cleanup" message