worktree-wizard

worktree-wizard

Run parallel feature branches with isolated Docker ports and data — zero config conflicts.

The problem: You're working on feature/auth with docker compose up, then need to context-switch to feature/payments. You either tear down your stack or get port conflicts. With worktree-wizard, each branch gets its own worktree with automatically offset ports and isolated data directories.

Quickstart

Using Claude Code (recommended — generates everything for you):

# Install the plugin
/plugin marketplace add asabedia/worktree-wizard
/plugin install worktree-wizard

# From your project repo, run the onboarding wizard
/wt-onboard

The wizard scans your project, asks a few questions, and generates your docker-compose.yml, justfile, Dockerfiles, and hot-reload configs.

Manual setup (4 steps):

# 1. Add to your project
git submodule add https://github.com/asabedia/worktree-wizard.git worktree-wizard

# 2. Create a justfile
echo 'import "worktree-wizard/worktree.just"' > justfile

# 3. Add wt.base-port labels to docker-compose.yml (see Setup section below)

# 4. Use it
just wt-dev feature/auth    # creates worktree + starts Docker + health-checks
cd .worktrees/feature/auth   # ready to work

How It Works

Each worktree gets a slot (1–9). Ports offset by slot number:

Slot	API	DB	Redis
0 (main)	8000	5432	6379
1	8001	5433	6380
2	8002	5434	6381

Data directories isolate per slot: .docker-data/slot-1/db/, .docker-data/slot-2/db/, etc.

Setup

Prerequisites

• just >= 1.19
• git
• docker + docker compose (for Docker features)
• jq (optional — improves YAML parsing; grep fallback works without it)

1. Add worktree-wizard to your project

Option A — git submodule (recommended, stays updated):

git submodule add https://github.com/asabedia/worktree-wizard.git worktree-wizard

Option B — copy (simpler, no submodule dependency):

cp -r /path/to/worktree-wizard ./worktree-wizard

2. Import in your justfile

Create a justfile in your project root (or add to your existing one):

import "worktree-wizard/worktree.just"

# your project recipes below
dev:
    npm run dev

3. Add labels to docker-compose.yml

Add wt.base-port labels to each service you want port-isolated. Use ${WT_*} env vars in the ports and volumes mappings with sensible defaults for slot 0 (main repo):

services:
  api:
    build: .
    labels:
      wt.base-port: "8000"            # tells worktree-wizard the base port
    ports:
      - "${WT_API_PORT:-8000}:8000"    # host port is dynamic, container port stays fixed

  db:
    image: postgres:16
    labels:
      wt.base-port: "5432"
      wt.data-dir: "/var/lib/postgresql/data"   # opt-in to data isolation
    ports:
      - "${WT_DB_PORT:-5432}:5432"
    volumes:
      - ${WT_DB_DATA:-./.docker-data/db}:/var/lib/postgresql/data

Key points:

• wt.base-port — the port number used in slot 0; worktree-wizard adds the slot number to compute the host port
• wt.data-dir — opt-in; tells worktree-wizard this service needs an isolated data directory per slot
• The :-default syntax means the main repo (slot 0) works without any env vars set
• Container-internal ports stay the same — only host-mapped ports change
• Services talk to each other via Docker's internal network (service names), unaffected by port offsets

4. Add to .gitignore

.worktrees/
.docker-data/
.env*.local

Usage

# Create a worktree for a new branch (off main by default)
just wt-new feature/auth

# Or branch off a specific base
just wt-new feature/auth develop

# cd into it
cd .worktrees/feature/auth

# Start services — ports are automatically offset
just wt-up -d

# Check your slot and port assignments
just wt-status
# → Slot: 1
# → WT_API_PORT=8001
# → WT_DB_PORT=5433

# View logs
just wt-logs

# Stop services
just wt-down

# When done, remove the worktree (from main repo)
cd ../..
just wt-rm feature/auth

You can run multiple worktrees simultaneously — each gets its own ports and data.

Agent-Ready Worktrees

wt-dev creates a worktree where an agent can immediately run tests — no manual Docker setup needed:

just wt-dev feature/auth

This runs the full bootstrap:

1. wt-doctor — verify git, just, docker, and project-specific tools
2. wt-new — create worktree, allocate slot, install deps, run hooks
3. wt-docker-ready — pull images, start services, TCP health-check all ports

When it finishes, every service is responding and the worktree is ready for just test.

Health Checks

Verify services are responding in the current worktree:

just wt-health

This TCP-probes every WT_*_PORT without restarting containers.

Requirement Checks