worktree

Worktree Management

List and create git worktrees using gtr (git-worktree-runner). Complements /git-cleanup to provide full worktree lifecycle: create → list/manage → cleanup.

When to Use

• Starting a new workstream and want branch isolation, then continuing work in the same session
• Creating a worktree and immediately executing a plan there (most common)
• Working on multiple features in parallel
• Checking what worktrees exist and their PR status
• Creating a worktree mid-session after realizing you need isolation

Arguments

Argument	Default	Description
list	(default)	List all worktrees with PR status and last commit
create <branch>	—	Create a new worktree for the given branch
create <branch> --from-current	—	Create a worktree branching from the current branch

Process

Command: list (default, no arguments)

1. Get worktree list:

   git gtr list
   

2. Enrich each worktree with PR status and last commit:

   # For each branch in the worktree list:
   gh pr list --head <branch> --state open --json number,title,url --limit 1
   git log -1 --format='%h %s (%cr)' <branch>
   

3. Display as a table:

   ## Worktrees
   
   | Path | Branch | PR | Last Commit |
   |------|--------|----|-------------|
   | ~/projects/myapp | main | — | abc1234 fix typo (2 hours ago) |
   | ~/projects/myapp-feat-auth | feat/auth | #42 Add OAuth | def5678 add token refresh (1 day ago) |
   | ~/projects/myapp-fix-bug | fix/login-bug | — | ghi9012 debug login (3 days ago) |
   

Command: create <branch-name>

1. If no branch name provided, ask for one using AskUserQuestion.

2. Preflight: ensure worktrees are stored inside the repo. Worktrees MUST be inside the repo so they stay within Claude Code's sandbox. Check and fix before creating:

   git gtr config get gtr.worktrees.dir
   

   • If it returns .worktrees → proceed to step 3.
   • If it returns anything else or is empty → configure it:

     # Add [worktrees] dir = .worktrees to .gtrconfig (create if missing)
     # If .gtrconfig doesn't exist:
     printf '[worktrees]\n  dir = .worktrees\n' > .gtrconfig
     # If .gtrconfig exists but has no [worktrees] section:
     # prepend the section before existing content
     
     # Ensure .worktrees/ is in .gitignore
     grep -qxF '/.worktrees/' .gitignore 2>/dev/null || echo '/.worktrees/' >> .gitignore
     

     Tell the user: "Configured this repo to store worktrees in .worktrees/ (inside the repo) so Claude Code can access them without permission prompts."