git-worktree-manager

Git Worktree Manager

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

Overview

Use this skill to run parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch.

This skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.

Core Capabilities

• Create worktrees from new or existing branches with deterministic naming
• Auto-allocate non-conflicting ports per worktree and persist assignments
• Copy local environment files (.env*) from main repo to new worktree
• Optionally install dependencies based on lockfile detection
• Detect stale worktrees and uncommitted changes before cleanup
• Identify merged branches and safely remove outdated worktrees

When to Use

• You need 2+ concurrent branches open locally
• You want isolated dev servers for feature, hotfix, and PR validation
• You are working with multiple agents that must not share a branch
• Your current branch is blocked but you need to ship a quick fix now
• You want repeatable cleanup instead of ad-hoc rm -rf operations

Key Workflows

1. Create a Fully-Prepared Worktree

1. Pick a branch name and worktree name.
2. Run the manager script (creates branch if missing).
3. Review generated port map.
4. Start app using allocated ports.

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/new-auth \
  --name wt-auth \
  --base-branch main \
  --install-deps \
  --format text

If you use JSON automation input:

cat config.json | python scripts/worktree_manager.py --format json
# or
python scripts/worktree_manager.py --input config.json --format json

2. Run Parallel Sessions

Recommended convention:

• Main repo: integration branch (main/develop) on default port
• Worktree A: feature branch + offset ports
• Worktree B: hotfix branch + next offset