worktree

name	worktree
description	Manage git worktrees for parallel Claude Code sessions. Use when user says "worktree", "create worktree", "parallel session", "new tree", or wants to work on multiple branches simultaneously.
allowed-tools	Bash, Glob, AskUserQuestion

Git Worktree Manager

Manage git worktrees for running parallel Claude Code sessions.

Commands

/worktree create <branch-name> [from <base-branch>]

Creates a new git worktree for parallel development.

Examples:

• /worktree create fix-bug - Creates worktree from origin/main
• /worktree create fix-bug from main - Creates worktree from main branch
• /worktree create feature-x from develop - Creates from develop

/worktree list

Lists all active worktrees.

/worktree remove [<worktree-name>]

Removes a worktree and its local branch.

---

Instructions

For create command:

1. Parse arguments:

   • <branch-name>: Required, the new branch name
   • <base-branch>: Optional, defaults to origin/main

2. Determine paths:

   REPO_BASENAME=$(basename "$PWD")
   WORKTREE_PATH="../${REPO_BASENAME}--${BRANCH_NAME}"
   ABSOLUTE_PATH=$(cd .. && pwd)/${REPO_BASENAME}--${BRANCH_NAME}
   

3. Fetch latest:

   git fetch origin
   

4. Create worktree:

   git worktree add -b <branch-name> <worktree-path> <base-branch>
   

5. Install dependencies:

   cd <worktree-path> && npm install
   

6. Return to original directory

7. CRITICAL - Output this format at the end:

   Worktree created successfully!
   
     Branch: <branch-name>
     Base:   <base-branch>
     Path:   <absolute-path>
   
   To start a parallel Claude Code session, copy and run:
   ┌────────────────────────────────────────────────────────────┐
   │ cd <absolute-path> && claude                               │
   └────────────────────────────────────────────────────────────┘
   

---

For list command:

Run and display output:

git worktree list

---

For remove command:

1. If no worktree name provided, show git worktree list and ask user to specify

2. Parse worktree name to extract branch:

   • Worktree format: <repo>--<branch>
   • Extract branch: everything after --

3. Ask for confirmation before proceeding

4. Remove worktree:

   git worktree remove <worktree-path> --force
   

5. Delete local branch:

   git branch -D <branch-name>
   

6. Confirm: "Removed worktree and local branch. Remote branch preserved for PR."

---

Safety Rules

• Always git fetch before creating to have latest refs
• Never remove worktrees with uncommitted changes without explicit confirmation
• Never remove the main worktree (one without -- in directory name)
• Preserve remote branches when removing (only delete local branch)
• If branch already exists, ask user if they want to use existing or create new name

Troubleshooting

Error: "fatal: '' is already checked out at ''"

Cause: The branch is already in use by another worktree Solution: Use git worktree list to find the existing worktree, then either remove it or choose a different branch name.

Error: "fatal: a branch named '' already exists"

Cause: Local branch with that name already exists Solution: Ask user if they want to reuse the existing branch or pick a new name.

Worktree remove fails with "contains modified or untracked files"

Cause: There are uncommitted changes in the worktree Solution: Ask user for explicit confirmation before using --force. Warn about potential data loss.