git-worktree-manager

name	git-worktree-manager
description	The Git Worktree Manager skill provides systematic management of Git worktrees for parallel development workflows. It handles worktree creation with automatic port allocation, environment file management, secret copying, and cleanup — enabling developers to run multiple Claude Code instances on separate features simultaneously without conflicts.
zh_description	用于Git、worktree、管理，支持开发、调试、评审和交付。
version	1.0.0
author	seaworld008
source	in-house
source_url
tags	["development", "git", "manager", "worktree"]
created_at	2026-03-04
updated_at	2026-03-20
quality	4
complexity	intermediate

Git Worktree Manager

Tier: POWERFUL
Category: Engineering
Domain: Parallel Development & Branch Isolation

Overview

The Git Worktree Manager skill provides systematic management of Git worktrees for parallel development workflows. It handles worktree creation with automatic port allocation, environment file management, secret copying, and cleanup — enabling developers to run multiple Claude Code instances on separate features simultaneously without conflicts.

Core Capabilities

• Worktree Lifecycle Management — create, list, switch, and cleanup worktrees with automated setup
• Port Allocation & Isolation — automatic port assignment per worktree to avoid dev server conflicts
• Environment Synchronization — copy .env files, secrets, and config between main and worktrees
• Docker Compose Overrides — generate per-worktree port override files for multi-service stacks
• Conflict Prevention — detect and warn about shared resources, database names, and API endpoints
• Cleanup & Pruning — safe removal with stale branch detection and uncommitted work warnings

When to Use This Skill

• Running multiple Claude Code sessions on different features simultaneously
• Working on a hotfix while a feature branch has uncommitted work
• Reviewing a PR while continuing development on your branch
• Parallel CI/testing against multiple branches
• Monorepo development with isolated package changes

Worktree Creation Workflow

Step 1: Create Worktree

# Create worktree for a new feature branch
git worktree add ../project-feature-auth -b feature/auth

# Create worktree from an existing remote branch
git worktree add ../project-fix-123 origin/fix/issue-123

# Create worktree with tracking
git worktree add --track -b feature/new-api ../project-new-api origin/main

Step 2: Environment Setup

After creating the worktree, automatically:

1. Copy environment files:

   cp .env ../project-feature-auth/.env
   cp .env.local ../project-feature-auth/.env.local 2>/dev/null