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

Pick a branch name and worktree name.
Run the manager script (creates branch if missing).
Review generated port map.
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

Each worktree contains .worktree-ports.json with assigned ports.

3. Cleanup with Safety Checks

Scan all worktrees and stale age.
Inspect dirty trees and branch merge status.
Remove only merged + clean worktrees, or force explicitly.

python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text

4. Docker Compose Pattern

Use per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to docker-compose.worktree.yml.

See docker-compose-patterns.md for concrete templates.

5. Port Allocation Strategy

Default strategy is base + (index * stride) with collision checks:

App: 3000
Postgres: 5432
Redis: 6379
Stride: 10

See port-allocation-strategy.md for the full strategy and edge cases.

Script Interfaces

python scripts/worktree_manager.py --help
- Create/list worktrees
- Allocate/persist ports
- Copy .env* files
- Optional dependency installation
python scripts/worktree_cleanup.py --help
- Stale detection by age
- Dirty-state detection
- Merged-branch detection
- Optional safe removal

Both tools support stdin JSON and --input file mode for automation pipelines.

Common Pitfalls

Creating worktrees inside the main repo directory
Reusing localhost:3000 across all branches
Sharing one database URL across isolated feature branches
Removing a worktree with uncommitted changes
Forgetting to prune old metadata after branch deletion
Assuming merged status without checking against the target branch

Best Practices

One branch per worktree, one agent per worktree.
Keep worktrees short-lived; remove after merge.
Use a deterministic naming pattern (wt-<topic>).
Persist port mappings in file, not memory or terminal notes.
Run cleanup scan weekly in active repos.
Use --format json for machine flows and --format text for human review.
Never force-remove dirty worktrees unless changes are intentionally discarded.

Validation Checklist

Before claiming setup complete:

git worktree list shows expected path + branch.
.worktree-ports.json exists and contains unique ports.
.env files copied successfully (if present in source repo).
Dependency install command exits with code 0 (if enabled).
Cleanup scan reports no unintended stale dirty trees.

References

port-allocation-strategy.md
docker-compose-patterns.md
README.md for quick start and installation details

Decision Matrix

Use this quick selector before creating a new worktree:

Need isolated dependencies and server ports -> create a new worktree
Need only a quick local diff review -> stay on current tree
Need hotfix while feature branch is dirty -> create dedicated hotfix worktree
Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day

Operational Checklist

Before Creation

Confirm main repo has clean baseline or intentional WIP commits.
Confirm target branch naming convention.
Confirm required base branch exists (main/develop).
Confirm no reserved local ports are already occupied by non-repo services.

After Creation

Verify git status branch matches expected branch.
Verify .worktree-ports.json exists.
Verify app boots on allocated app port.
Verify DB and cache endpoints target isolated ports.

Before Removal

Verify branch has upstream and is merged when intended.
Verify no uncommitted files remain.
Verify no running containers/processes depend on this worktree path.

CI and Team Integration

Use worktree path naming that maps to task ID (wt-1234-auth).
Include the worktree path in terminal title to avoid wrong-window commits.
In automated setups, persist creation metadata in CI artifacts/logs.
Trigger cleanup report in scheduled jobs and post summary to team channel.

Failure Recovery

If git worktree add fails due to existing path: inspect path, do not overwrite.
If dependency install fails: keep worktree created, mark status and continue manual recovery.
If env copy fails: continue with warning and explicit missing file list.
If port allocation collides with external service: rerun with adjusted base ports.