git-worktree-setup

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

Version History

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

Last Updated

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