worktree

name	worktree
description	Create a git worktree for reviewing an MR/PR or working on a branch in isolation. Use when the user wants to review a merge request or pull request, check out a branch in a separate worktree, or uses /worktree. Accepts an MR/PR number, an MR/PR URL, or a branch name. Creates the worktree under .claude/worktrees/, copies gitignored environment files from the main worktree, bootstraps the project, and switches the session into it.
allowed-tools	Bash(git *), Bash(glab *), Bash(gh *), Bash(cp *), Bash(mkdir *), Bash(direnv *), Bash(just *), Bash(uv *), Bash(npm *), Bash(bun *), Bash(pnpm *), Bash(jq *), Read

Worktree

Create an isolated git worktree for reviewing or working on a branch.

Workflow

1. Resolve the target branch:

   • MR number (digits, GitLab remote): glab mr view <n> --output json | jq -r '.source_branch'
   • PR number (digits, GitHub remote): gh pr view <n> --json headRefName --jq '.headRefName'
   • MR URL (contains /merge_requests/): extract the number, resolve as above.
   • PR URL (contains /pull/): extract the number, resolve as above.
   • Branch name: use directly.

   To pick between glab and gh when given bare digits, inspect git remote get-url origin: substring gitlab -> glab, substring github -> gh.

2. Create the worktree:

   • git fetch origin
   • mkdir -p .claude/worktrees
   • If origin/<branch> exists: git worktree add .claude/worktrees/<dir> origin/<branch>
   • Else if the branch exists locally: git worktree add .claude/worktrees/<dir> <branch>
   • Else (branch does not exist): create it from HEAD: git worktree add -b <branch> .claude/worktrees/<dir> HEAD
   • If the branch name contains /, replace with - in the directory name only.

3. Copy gitignored environment files from the main worktree root to the new worktree. Run git ls-files --others --ignored --exclude-standard to identify gitignored files present locally. From that list, copy only:

   • .env, .env.* files (environment variables)
   • .envrc (direnv configuration)

   Skip everything else. Directories like .venv/, node_modules/, build/, dist/, __pycache__/, and tooling state like .claude/, .llm/, .coverage*, .DS_Store are either regenerated by setup or not needed.

   Only copy files confirmed as gitignored. Tracked files are already in the worktree from the checkout.

4. Bootstrap the environment. Run setup commands using full worktree paths (the session has not entered the worktree yet).

   First, check: does .envrc exist in the worktree (either tracked by git or copied in step 3)? If yes, run direnv allow .claude/worktrees/<dir> and skip the rest of this step -- direnv handles venv activation, dependency installation, and all other setup.

   Fallback (no .envrc): bootstrap manually:

   • If pyproject.toml exists: uv sync --all-groups --directory .claude/worktrees/<dir>
   • If package.json exists, pick the manager by lock file (use --cwd or --prefix as appropriate):
     • bun.lock or bunfig.toml: bun install --cwd .claude/worktrees/<dir>
     • pnpm-lock.yaml: pnpm install --dir .claude/worktrees/<dir>
     • package-lock.json: npm install --prefix .claude/worktrees/<dir>

   In either case, if a justfile exists, run just --list and mention available setup targets to the user. Do not run them without asking.

5. Enter the worktree. Call the EnterWorktree tool (not a Bash command) with the path parameter set to the worktree path (e.g., .claude/worktrees/<dir>). This switches the session's working directory into the worktree so commands run there naturally.

6. Report the worktree path and summarize what was done: branch checked out, files copied, setup commands run.

Cleanup

ExitWorktree with action: "remove" will NOT work here -- it only removes worktrees that EnterWorktree itself created. This skill creates worktrees manually with git worktree add because EnterWorktree cannot check out a specific existing branch (it only creates new branches from HEAD or origin/main).

When the user is done with the worktree:

1. Call ExitWorktree with action: "keep" to leave the worktree and return to the original directory.
2. git worktree remove .claude/worktrees/<dir>
3. If a temporary local branch was created (step 2, "branch does not exist" case), delete it: git branch -d <branch>

Rules

• Always use plain git commands (no -C flag, it breaks permission matching) in steps 1-4 before entering the worktree.
• The worktree directory is always under .claude/worktrees/ relative to repo root.
• Only copy gitignored files. Never overwrite tracked files in the worktree with versions from the main worktree.
• Do not run database migrations or destructive setup targets without asking.