Git Worktree Setup Skill

Guide creation of isolated Git worktree environments for parallel agent execution.

When to Use

Setting up parallel agent execution
Creating isolated development environments
Configuring port allocation for multiple instances
Planning worktree directory structure

Core Concepts

Why Worktrees?

Git worktrees provide:

Filesystem isolation per agent
Shared Git object database
Independent branches
Clean checkout from origin/main

Directory Structure

repository_root/
├── trees/
│   ├── {adw_id}/           # Isolated worktree
│   │   ├── src/
│   │   ├── .ports.env
│   │   └── ...
│   └── ...                  # Up to 15 concurrent
├── agents/
│   └── {adw_id}/
│       └── adw_state.json
└── main codebase/

Port Allocation

Deterministic formula:

slot = hash(adw_id) % 15
backend_port = 9100 + slot
frontend_port = 9200 + slot

Setup Workflow

Step 1: Plan Worktree Location

Identify where worktrees should live:

Default: trees/{adw_id}/
Alternative: .worktrees/{adw_id}/

Step 2: Create Worktree

Commands to execute:

# Fetch latest
git fetch origin

# Create worktree with new branch
git worktree add trees/{adw_id} -b {branch_name} origin/main

Step 3: Configure Ports

Create .ports.env:

BACKEND_PORT={backend_port}
FRONTEND_PORT={frontend_port}
VITE_BACKEND_URL=http://localhost:{backend_port}

Step 4: Copy Environment

cp .env trees/{adw_id}/.env
cat trees/{adw_id}/.ports.env >> trees/{adw_id}/.env

Step 5: Update Configurations

For any absolute path configurations (MCP, etc.):

Update paths to point to worktree location
Use absolute paths, not relative

Step 6: Install Dependencies

cd trees/{adw_id}
# Backend dependencies
cd app/server && uv sync --all-extras
# Frontend dependencies
cd app/client && bun install

Validation Checklist

After setup, validate:

Cleanup Operations

Remove Single Worktree

git worktree remove trees/{adw_id}
# Or force if uncommitted changes
git worktree remove trees/{adw_id} --force

Prune Stale Worktrees

git worktree prune

List All Worktrees

git worktree list

Key Memory References

@git-worktree-patterns.md - Full worktree documentation
@adw-anatomy.md - ADW uses worktrees
@zte-progression.md - ZTE requires parallelization

Output Format

Provide setup plan:

## Worktree Setup Plan

**ADW ID:** {adw_id}
**Branch Name:** {branch_name}
**Worktree Path:** trees/{adw_id}

### Port Allocation
- Backend: {backend_port}
- Frontend: {frontend_port}

### Commands to Execute
1. `git fetch origin`
2. `git worktree add trees/{adw_id} -b {branch_name} origin/main`
3. Create `.ports.env`
4. Copy and configure environment
5. Install dependencies

### Validation Steps
- [ ] Verify worktree created
- [ ] Test port availability
- [ ] Confirm dependencies installed

Troubleshooting

Issue	Solution
Worktree already exists	Remove first or use different ID
Port in use	Check what's using it, kill or use different
Branch exists	Use existing branch or delete first
Permission denied	Check directory permissions

Version History

v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101

git-worktree-setup