Worktree Manager
Safe git worktree operations that prevent the CWD deletion error that breaks Claude's shell.
Instructions
CRITICAL: Never use git worktree remove directly. Always use the cleanup script with proper CWD handling.
⚠️ CWD Safety (MANDATORY)
ALWAYS cd to project root BEFORE running the cleanup script.
The cleanup script runs in a subshell, so its internal cd does NOT affect your shell session.
If you're inside the worktree when it's deleted, your shell breaks permanently for the session.
# ✅ CORRECT: Use git rev-parse to reliably get project root, then chain with cleanup
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123 --delete-branch
# ❌ WRONG: Running directly while inside the worktree breaks the shell
${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123 --delete-branch
Available Scripts
All scripts are located in ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/:
| Script | Usage |
|---|---|
worktree-create.sh |
<task-id> <description> [--base-branch <branch>] |
worktree-list.sh |
[--json] [--verbose] |
worktree-status.sh |
<worktree-path> |
worktree-cleanup.sh |
<worktree-path> --keep-branch|--delete-branch [--force] [--dry-run] [--timeout <sec>] [--network-timeout <sec>] [--skip-lock-check] |
Safe Worktree Removal
Remember: Always cd to project root first (see CWD Safety above).
IMPORTANT: You must specify branch disposition for non-protected branches:
--keep-branch- Keep the branch for future work--delete-branch- Delete the branch (after merge)
Protected branches (develop, main, master) are never deleted.
# After merge: delete the branch (always cd to project root first!)
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-description --delete-branch
# Keep branch for later
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-description --keep-branch
Why This Matters
When Claude removes a worktree while the shell's CWD is inside that worktree:
git worktree removefails with "directory in use"- If forced, the directory is deleted but the shell's CWD becomes invalid
- All subsequent Bash commands fail for the remainder of the session
Important: The cleanup script's internal cd runs in a subshell and does NOT change Claude's shell CWD. You MUST cd to project root in your own command BEFORE running the script.
Examples
Create a new worktree
${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-create.sh PROJ-123 auth-feature
# Creates: ./.claude/worktrees/PROJ-123-auth-feature with branch feature/PROJ-123-auth-feature
List all worktrees with status
${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-list.sh --verbose
Check worktree health
${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-status.sh ./.claude/worktrees/PROJ-123-auth-feature
Safely remove a worktree (delete branch after merge)
# ALWAYS cd to project root first!
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --delete-branch
Safely remove a worktree (keep branch for later)
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --keep-branch
Preview what would happen
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --delete-branch --dry-run
Force remove (emergency, with uncommitted changes)
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --delete-branch --force
Custom timeout for large worktrees (monorepos, heavy node_modules)
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --delete-branch --timeout 300
Skip lock detection for CI/headless environments
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --delete-branch --skip-lock-check
Custom network timeout for slow remotes
cd "$(git rev-parse --show-toplevel)" && ${CLAUDE_PLUGIN_ROOT}/skills/worktree-manager/scripts/worktree-cleanup.sh ./.claude/worktrees/PROJ-123-auth-feature --delete-branch --network-timeout 60
Converted and distributed by TomeVault — claim your Tome and manage your conversions.