Quick Create Worktrees

Create and manage Git worktrees for parallel development across multiple branches without stashing or switching.

When to Use This Command

Run this command when you need to:

• Work on multiple branches simultaneously without switching or stashing changes
• Create worktrees for all open pull requests to review or test them in parallel
• Set up isolated working directories for hotfixes while continuing feature development

Consider alternatives when:

• You only need to check one other branch briefly (a simple git stash and switch is faster)
• You are working in a shallow clone or a repository that does not support worktrees

Quick Start

Configuration

Copy
name: quick-create-worktrees
type: command
category: git-workflow

Example Invocation

Copy
claude command:run quick-create-worktrees --action create --branch feature/new-dashboard

Example Output

Worktree Operation: create
Branch: feature/new-dashboard
Location: ./tree/feature/new-dashboard

Pre-flight:
  [OK] Branch exists on remote (origin/feature/new-dashboard)
  [OK] No existing worktree for this branch
  [OK] Target directory is available

Execution:
  [+] Fetched latest from origin
  [+] Created worktree at: ./tree/feature/new-dashboard
  [+] HEAD at: e4f5g6h (feature/new-dashboard: "Add dashboard layout")

Active Worktrees:
  /path/to/repo                              main
  /path/to/repo/tree/feature/new-dashboard   feature/new-dashboard
  /path/to/repo/tree/bugfix/login-fix        bugfix/login-fix

To work in this worktree: cd ./tree/feature/new-dashboard

Core Concepts

Git Worktree Overview

Aspect	Details
Isolation	Each worktree has its own working directory and index
Shared Repository	All worktrees share the same .git repository and object store
Branch Locking	A branch can only be checked out in one worktree at a time
PR Worktrees	Batch-create worktrees for all open pull requests
Cleanup	Remove worktrees for merged or deleted branches automatically

Worktree Management Workflow

  Worktree Request
       |
       v
  +-------------------+
  | Fetch Remote      |---> Get latest branch refs
  +-------------------+
       |
       v
  +-------------------+
  | Validate Branch   |---> Exists? Already checked out?
  +-------------------+
       |
       v
  +-------------------+
  | Create Directory  |---> ./tree/branch-name/
  +-------------------+
       |
       v
  +-------------------+
  | git worktree add  |---> Link worktree to branch
  +-------------------+
       |
       v
  +-------------------+
  | List All Trees    |---> Show active worktrees
  +-------------------+

Configuration

Parameter	Type	Default	Description
action	string	create	Worktree action: create, remove, list, cleanup, create-all-prs
branch	string	required	Branch name for the worktree (not needed for list/cleanup)
base_dir	string	./tree	Parent directory where worktree directories are created
new_branch	boolean	false	Create a new branch and worktree simultaneously
base	string	HEAD	Base commit or branch for new branch creation

Best Practices

1. Use a Consistent Worktree Directory - Keep all worktrees under a single ./tree/ directory in the repository root. This makes it easy to find, list, and clean up worktrees and keeps the project structure predictable.

2. Clean Up After Merging - Remove worktrees for branches that have been merged. Stale worktrees consume disk space and clutter the worktree list, making it harder to find active work.

3. Use Worktrees for Code Review - Instead of stashing your work and switching branches to review a PR, create a worktree. This lets you keep your work in progress untouched while reviewing in a separate directory.

4. Batch-Create for PR Review Sessions - When reviewing multiple PRs, use the create-all-prs action to create worktrees for every open PR at once. This eliminates the overhead of switching context between reviews.

5. Exclude Worktree Directory from Git - Add the tree/ directory to .gitignore so worktree directories are not accidentally tracked. Worktrees are local development infrastructure, not project content.

Common Issues

1. Branch Already Checked Out Error - Git prevents checking out the same branch in multiple worktrees. If you need to work on the branch that is checked out in the main repo, switch the main repo to a different branch first.

2. Worktree Directory Already Exists - A previous worktree was not properly removed. Use git worktree remove to clean up the old worktree before creating a new one at the same path.

3. Dependencies Not Installed in Worktree - The new worktree has no node_modules or virtual environment. Run the package install command in the new worktree directory since dependencies are not shared between worktrees.