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:

• Worktree directory exists

• Git recognizes worktree (git worktree list )

• Branch is correct

• Ports are configured

• Environment files present

• Dependencies installed

• Application can start

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