git-worktree-manager

---
name: git-worktree-manager
description: Use when running multiple feature branches simultaneously, isolating experimental work, or coordinating multi-agent development so each worktree gets isolated branches, ports, and environment sync.
category: Engineering
version: 1.0.0
tools: []
---

# Git Worktree Manager

Standardize branch isolation, port allocation, environment sync, and cleanup so each parallel git worktree behaves like an independent local app, without one branch stepping on another. Optimized for multi-agent workflows where each agent or terminal session owns one worktree.

## Core Capabilities

- Deterministic naming for worktrees created from new or existing branches
- Non-conflicting port allocation per worktree, persisted for reuse
- Environment file (`.env*`) sync from the main repo to each new worktree
- Dependency-install guidance based on lockfile detection
- Stale-worktree and uncommitted-change detection before cleanup
- Merged-branch detection so only safe worktrees are removed

## When to Use

- 2+ concurrent branches need to be open locally
- Isolated dev servers are needed for feature, hotfix, and PR validation
- Multiple agents must not share a branch
- The current branch is blocked but a quick fix must ship now
- Repeatable cleanup is needed instead of ad-hoc deletion

## Key Workflows

### 1. Create a Fully-Prepared Worktree

1. Pick a branch name and worktree name.
2. Create the branch if it doesn't exist, and the worktree alongside it.
3. Allocate and record a port map for the new worktree.
4. Start the app using the allocated ports.

### 2. Run Parallel Sessions

Recommended convention:

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

Record each worktree's assigned ports so they don't collide.

### 3. Cleanup with Safety Checks

1. Scan all worktrees and note staleness by age (default threshold: 14 days).
2. Inspect for dirty (uncommitted) trees and branch merge status.
3. Remove only merged and clean worktrees; require explicit confirmation to force-remove a dirty one.

### 4. Docker Compose Pattern

Use per-worktree override files mapped from the allocated ports, so each worktree's containers stay isolated.

### 5. Port Allocation Strategy

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

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

## Common Pitfalls

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

## Best Practices

1. One branch per worktree, one agent per worktree.
2. Keep worktrees short-lived; remove after merge.
3. Use a deterministic naming pattern (`wt-<topic>`).
4. Persist port mappings rather than relying on memory or terminal notes.
5. Run a cleanup scan weekly in active repos.
6. Never force-remove dirty worktrees unless changes are intentionally discarded.

## 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 a hotfix while the feature branch is dirty -> create a dedicated hotfix worktree
- Need an ephemeral reproduction branch for bug triage -> create a temporary worktree and clean up the same day

## Operational Checklist

### Before Creation

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

### After Creation

1. Verify the branch matches what was expected.
2. Verify the port map exists and is unique.
3. Verify the app boots on its allocated port.
4. Verify DB and cache endpoints target isolated ports.

### Before Removal

1. Verify the branch has an upstream and is merged when intended.
2. Verify no uncommitted files remain.
3. Verify no running containers or processes depend on this worktree path.

## CI and Team Integration

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

## Failure Recovery

- If worktree creation fails because the path already exists: inspect the path, do not overwrite.
- If dependency install fails: keep the worktree, mark its status, and continue manual recovery.
- If env file copy fails: continue with a warning and an explicit missing-file list.
- If port allocation collides with an external service: rerun with adjusted base ports.