worktree

name: worktree description: Use when starting new feature work that should happen in an isolated git worktree on its own branch. argument-hint: <task description or branch name> allowed-tools: Bash

input = $ARGUMENTS

Branch Name

Derive from user input (ask if missing). Default format: <type>/<kebab-description> using conventional commit types (feat when ambiguous). Check git branch first — if the repo uses a different convention (e.g., feature/JIRA-123-desc), match it.

Show the derived name before proceeding.

Worktree Location

• {repo_root}/.claude/worktrees/{branch_slug} where branch_slug replaces / with -
• repo_root = git rev-parse --show-toplevel
• Ensure .claude/worktrees/ exists and is in .gitignore

Base Branch

Branch from the latest remote default, not from HEAD — HEAD can be stale or on an unrelated branch, silently seeding the worktree with the wrong history.

1. Detect default: git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||' (fallback: try main, then master)
2. Fetch: git fetch origin {default_branch}
3. Create: git worktree add -b {branch} {directory} origin/{default_branch}

If the branch already exists: git worktree add {directory} {branch} (no -b).

After creation, symlink gitignored files so the worktree runs without a reinstall:

bash ~/.claude/skills/worktree/scripts/symlink-gitignored.sh {repo_root} {directory}

Submodules

git worktree add on a parent repo does NOT initialize submodules — their directories will be empty. Each worktree gets its own independent submodule git dir at .git/worktrees/{name}/modules/{submodule}, so submodules can be on different branches without conflicting with the original checkout.

Inside the new worktree:

1. Initialize: git -C {directory} submodule update --init
2. If the submodule needs a specific branch (not just the commit pinned by the parent): git -C {directory}/{submodule} checkout {branch}
3. Symlink gitignored files per submodule:

   bash ~/.claude/skills/worktree/scripts/symlink-gitignored.sh {repo_root}/{submodule} {directory}/{submodule}
   

Scope determination — before creating anything:

• Single submodule only — worktree in that submodule alone
• Parent + submodule(s) — parent worktree + submodule init inside it
• Ambiguous — ask

Output

Show: worktree path, claude --cwd {directory} command, reminder to use /worktree-clean when done, and git worktree list.