Wtc

wtc — worktree-compose

Zero-config Docker Compose isolation for git worktrees. Each worktree gets its own containers, ports, and volumes — no conflicts when running multiple branches simultaneously.

Repo: https://github.com/LevwTech/worktree-compose

Port Formula

remapped_port = 20000 + default_port + worktree_index

Worktree index comes from position in git worktree list. Run wtc ls to see current assignments.

Port Collision Problem

The default formula 20000 + port + index creates collisions when services have consecutive ports:

Service ports: 8001, 8002, 8003, 8004

WT1: 28002, 28003, 28004, 28005
WT2: 28003, 28004, 28005, 28006  ← overlaps WT1
WT3: 28004, 28005, 28006, 28007  ← overlaps WT1 & WT2

Fix: Use index * 100 offset instead of just index:

WT1: 28101, 28102, 28103, 28104
WT2: 28201, 28202, 28203, 28204  ← no overlap
WT3: 28301, 28302, 28303, 28304  ← no overlap

After wtc start, run the fix script inside the worktree:

cd <worktree-path>
bash "${HOME}/.agents/skills/wtc/scripts/wtc-fix-ports"

The script auto-detects the worktree index from known infra ports (postgres, redis, etc.) and fixes ALL *_PORT variables in .env.

Database Readiness

wtc isolates Docker infra. It does NOT guarantee database state.

After wtc start, before starting your app:

1. Verify database is reachable on the remapped port
2. Run migrations if needed
3. Run seeds if needed

Do NOT assume a running database means migrations are applied or seed data exists.

Commands

CRITICAL: Always run wtc from the repo root, not from inside a worktree.

wtc ls                  # list all worktrees with indices, status, ports
wtc start 1 3           # start infra for worktrees by index
wtc stop 1 3            # stop (preserves volumes)
wtc restart 1           # stop → resync → rebuild → start
wtc promote 1           # copy worktree changes into current branch
wtc clean               # stop all, remove all worktrees + prune Docker (DESTRUCTIVE)

Workflow

# 1. From repo root
cd /path/to/repo
wtc ls                    # see worktree indices
wtc start <index>         # start Docker infra

# 2. Move into worktree
cd <worktree-path>

# 3. Fix port collisions (if project has consecutive service ports)
bash "${HOME}/.agents/skills/wtc/scripts/wtc-fix-ports"

# 4. Check database readiness
# Run migrations/seeds if needed

# 5. Start app (project-specific)
# e.g., make dev, pnpm dev, npm run dev

What wtc Does

1. Creates isolated Docker Compose project per worktree
2. Remaps ports so each worktree has unique ports
3. Syncs docker-compose.yml and .env from main branch
4. Injects port overrides into worktree's .env

What wtc Does NOT Do

• Start your app servers (backend, frontend)
• Run database migrations
• Seed data
• Manage browser automation
• Fix port collisions automatically (you need to patch .env)

These are project-specific — handle them via Makefile, scripts, or the repo's instructions file.

Port Requirements

wtc can only remap ports declared with env var defaults:

# wtc can remap
ports:
  - "${POSTGRES_PORT:-5432}:5432"

# wtc skips (hardcoded)
ports:
  - "5432:5432"

Gotchas

• Run from repo root — wtc derives project name from current directory
• wtc syncs from main — worktree-local docker-compose.yml changes are overwritten
• --build flag — wtc start runs docker compose up -d --build, which checks network for image updates. For fast startup after first run, use wtc-up script (see below).
• Consecutive ports collide — see Port Collision Problem above

Optional: wtc as MCP Server

{
  "mcpServers": {
    "wtc": {
      "command": "npx",
      "args": ["wtc", "mcp"]
    }
  }
}

Optional: .wtcrc.json

{
  "sync": [".generated/prisma-client"],
  "envOverrides": {
    "VITE_API_URL": "http://localhost:${BACKEND_PORT}"
  }
}

Scripts Bundled with This Skill

wtc-up (Fast Startup)

wtc start always uses --build which checks network for base image updates. Use wtc-up for fast startup:

cd <worktree-path>
bash "${HOME}/.agents/skills/wtc/scripts/wtc-up"

When to use which:

• wtc start <index> — First time setup, or after Dockerfile changes
• wtc-up — Daily startup, images already built, no network checks

Additional Resources

See DECISIONS.md for the reasoning behind design decisions in this skill.

Source: 0-sayed/auto-pr — distributed by TomeVault.