git-worktree-setup

cskiro's avatarfrom cskiro

Use PROACTIVELY when working on multiple branches simultaneously or creating parallel Claude Code sessions. Automates git worktree creation with prerequisite checking, development environment initialization, and safe cleanup. Supports single worktree, batch creation, and worktree removal. Not for non-git projects or branch management without worktrees.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 14, 2025
[Developer Tools]

When & Why to Use This Skill

Git Worktree Setup is a specialized automation tool designed to streamline multi-branch development workflows. It simplifies the creation and management of git worktrees, enabling developers to work on multiple features or hotfixes simultaneously without the overhead of stashing or context switching. By automating environment initialization, dependency installation, and safety checks, it ensures a seamless transition between parallel coding sessions, making it an essential utility for high-velocity software engineering and parallel AI-assisted coding.

Use Cases

  • Parallel Feature Development: Create isolated worktrees for multiple feature branches to work on them concurrently without the friction of frequent branch switching.
  • Emergency Hotfix Management: Quickly spin up a clean environment for urgent bug fixes while maintaining the exact state of your current long-running development branch.
  • Streamlined Code Reviews: Set up a dedicated worktree to review and test a colleague's pull request locally without interrupting your own active workspace or build artifacts.
  • Automated Environment Setup: Automatically detect package managers (npm, yarn, pnpm, bun) and install dependencies when creating new worktrees to ensure immediate readiness for coding.
  • Parallel AI Coding Sessions: Efficiently manage multiple Claude Code sessions across different branches by providing unique, conflict-free file paths for each agent.
namegit-worktree-setup
version0.2.1
descriptionUse PROACTIVELY when working on multiple branches simultaneously or creating parallel Claude Code sessions. Automates git worktree creation with prerequisite checking, development environment initialization, and safe cleanup. Supports single worktree, batch creation, and worktree removal. Not for non-git projects or branch management without worktrees.

Git Worktree Setup

Automates git worktree creation for parallel Claude Code sessions without conflicts.

When to Use

Trigger Phrases:

  • "create a worktree for [branch-name]"
  • "set up worktree for [feature]"
  • "create worktrees for [branch1], [branch2]"
  • "remove worktree [name]"
  • "list my worktrees"

Use Cases:

  • Working on multiple features simultaneously
  • Parallel Claude Code sessions on different branches
  • Code review while continuing development
  • Emergency hotfixes without interrupting work

Quick Decision Matrix

Request Mode Action
"create worktree for X" Single Create one worktree
"set up worktrees for X, Y" Batch Create multiple
"remove worktree X" Cleanup Remove specific
"list worktrees" List Display status

Workflow Overview

Phase 0: Prerequisites (Mandatory)

# Verify git repo
git rev-parse --is-inside-work-tree

# Check uncommitted changes
git status --porcelain

# Get repo name
basename $(git rev-parse --show-toplevel)

Phase 1: Gather Information

  • Branch name (required)
  • New or existing branch
  • Location (default: ../repo-branch)
  • Setup dev environment

Phase 2: Create Worktree

# New branch
git worktree add ../project-feature -b feature

# Existing branch
git worktree add ../project-bugfix bugfix

Phase 3: Dev Environment Setup

  • Detect package manager
  • Run install
  • Copy .env files

Phase 4: Next Steps

  • Show worktree path
  • Provide navigation commands
  • List all worktrees

Quick Reference Commands

# Create with new branch
git worktree add ../project-branch -b branch-name

# Create from existing
git worktree add ../project-branch branch-name

# List all
git worktree list

# Remove worktree
git worktree remove ../project-branch

# Remove worktree and branch
git worktree remove ../project-branch
git branch -D branch-name

Package Manager Detection

Lock File Manager
pnpm-lock.yaml pnpm
yarn.lock yarn
bun.lockb bun
package-lock.json npm

Common Issues

Issue Cause Fix
"invalid reference" Branch doesn't exist Use -b for new
"already exists" Directory exists Choose different location
"uncommitted changes" Dirty working dir Commit or stash

Safety Protocols

Before Creating:

  • Verify git repository
  • Check clean working directory
  • Validate target directory available

Before Cleanup:

  • Confirm user intent
  • Check for uncommitted changes
  • Warn about permanent branch deletion

Example Output

✓ Worktree created: /Users/connor/myapp-feature-auth
✓ Branch: feature-auth (new)
✓ Dependencies installed

Next steps:
  cd ../myapp-feature-auth
  claude

All worktrees:
- /path/to/main (main) ← current
- /path/to/worktree (feature-auth) ← new

Success Criteria

  • Worktree in correct location
  • Branch checked out properly
  • Files visible in directory
  • Dev environment ready
  • Appears in git worktree list
  • User can start Claude Code

Reference Materials

  • modes/ - Detailed mode workflows
  • templates/ - Setup script templates
  • data/best-practices.md
  • data/troubleshooting.md

Version: 1.0.0 | Author: Connor