worktree-compose · wtc

Zero-config Docker Compose isolation for git worktrees

Every worktree gets its own ports, database, cache, and containers — automatically.

The full wtc workflow: an isolated Docker stack per worktree, several AI agents building in parallel, compared live on their own ports — then promote the winner.

npm install -D worktree-compose

npx wtc list

┌───────┬───────────────┬────────┬────────────────────────┬─────────────────────────────────────────────────────────┐
│ Index │ Branch        │ Status │ URL                    │ Ports                                                   │
├───────┼───────────────┼────────┼────────────────────────┼─────────────────────────────────────────────────────────┤
│ -     │ main          │ -      │ -                      │ postgres:5434 redis:6380 backend:8000 frontend:5173     │
├───────┼───────────────┼────────┼────────────────────────┼─────────────────────────────────────────────────────────┤
│ 1     │ feature-auth  │ up     │ http://localhost:25174 │ postgres:25435 redis:26381 backend:28001 frontend:25174 │
├───────┼───────────────┼────────┼────────────────────────┼─────────────────────────────────────────────────────────┤
│ 2     │ fix-billing   │ down   │ http://localhost:25175 │ postgres:25436 redis:26382 backend:28002 frontend:25175 │
└───────┴───────────────┴────────┴────────────────────────┴─────────────────────────────────────────────────────────┘

• Why wtc?
• How is this different from docker compose -p?
• Quick Start
• Usage
• Preparing your docker-compose.yml
• How It Works
• Commands
• Configuration (Optional)
• MCP Server
• Full Example
• Requirements
• Troubleshooting
• Contributing
• License

Spin up multiple developers or AI agents on the same repo — each in its own git worktree — and they immediately fight over a single Docker Compose setup: port conflicts, a shared database, a shared cache, colliding containers. You can't run two stacks side by side.

wtc reads your existing docker-compose.yml and turns every worktree into a fully isolated, side-by-side environment — unique host ports, separate containers, networks, and volumes — with zero configuration.

• ⚡ Zero config — reads your existing docker-compose.yml, no new files required
• 🔌 Automatic ports — unique, collision-free host ports per worktree
• 📦 Full isolation — separate containers, networks, and volumes for each stack
• 🧪 True side-by-side — run N stacks at once and compare them in the browser
• 🔄 One-command promote — pull a worktree's changes back into your branch
• 🤖 Built-in MCP server — let AI agents start, stop, and manage their own stacks

git worktree add ../app-feat feat
# hand-pick non-colliding host ports
# edit ../app-feat/.env per service
# copy compose file + Dockerfiles over
docker compose -p app-feat up -d --build
# ...remember to tear it all down later

git worktree add ../app-feat feat
wtc start

# ...and when you're done:
wtc clean

docker compose -p only namespaces the project. You'd still hand-pick free host ports, hand-edit each worktree's .env, copy infra files in, and tear everything down yourself. wtc builds on that same project-name isolation and automates the rest: collision-free port allocation, per-worktree .env injection, infra-file sync, one-command promote, and a built-in MCP server so AI agents can drive it all themselves.

# 1. Install
npm install -D worktree-compose

# 2. Create a worktree for some parallel work
git worktree add ../myapp-feature feature-branch

# 3. Boot an isolated stack for it
npx wtc start

# 4. See everything that's running
npx wtc list

# Start isolated stacks for all worktrees
npx wtc start

# Start specific worktrees
npx wtc start 1
npx wtc start 1 2 3

# See what's running
npx wtc list

# Stop worktrees
npx wtc stop
npx wtc stop 1

# Restart (re-sync files, rebuild containers)
npx wtc restart 1

# Pull a worktree's changes into your current branch
npx wtc promote 1

# Tear down everything (containers, worktrees, volumes)
npx wtc clean

For wtc to isolate a service's port, the host port must use the ${VAR:-default} pattern:

# wtc CAN isolate this
ports:
  - "${BACKEND_PORT:-8000}:8000"

# wtc CANNOT isolate this (hardcoded)
ports:
  - "8080:8080"

If wtc finds hardcoded ports, it warns you and suggests the fix:

⚠ Service "nginx" uses a raw port mapping (8080:80).
  To enable port isolation, change it to: "${NGINX_PORT:-8080}:80"

# Standard
- "${BACKEND_PORT:-8000}:8000"

# Same var for host and container
- "${FRONTEND_PORT:-5173}:${FRONTEND_PORT:-5173}"

# IP-bound
- "127.0.0.1:${API_PORT:-3000}:3000"

# With protocol
- "${BACKEND_PORT:-8000}:8000/tcp"

# Multiple ports per service
- "${BACKEND_PORT:-8000}:8000"
- "${DEBUG_PORT:-9229}:9229"

# Long-form syntax
- target: 8000
  published: "${BACKEND_PORT:-8000}"
  protocol: tcp

Each worktree N gets unique ports: 20000 + default_port + worktree_index

The table is illustrative — every value follows the formula above. (If an allocation would exceed 65535, wtc falls back to default_port + 100 × index.)

Each worktree gets its own COMPOSE_PROJECT_NAME — {repo}-wt-{index}-{branch}, lowercased and sanitized to a Docker-safe name. That means separate containers, networks, and volumes. Nothing is shared.

Before starting, wtc copies infrastructure files from main into each worktree: the compose file, every Dockerfile referenced by a service's build, and your base .env (falling back to .env.example, or an empty file if neither exists). This keeps every worktree on the latest Docker setup.

After copying .env, wtc appends an idempotent block with allocated port overrides:

# existing .env content stays untouched...

# --- wtc port overrides ---
POSTGRES_PORT=25435
REDIS_PORT=26381
BACKEND_PORT=28001
FRONTEND_PORT=25174
# --- end wtc ---

Re-running wtc start strips and rewrites this block, so it never accumulates.

Start Docker Compose stacks. Syncs files, injects ports, runs docker compose up -d --build.

npx wtc start         # all worktrees
npx wtc start 1       # worktree 1 only
npx wtc start 1 2 3   # worktrees 1, 2, and 3

Stop stacks. Runs docker compose down. Volumes are preserved.

npx wtc stop          # all
npx wtc stop 1        # worktree 1 only

Full restart: stop, re-sync files, re-inject env, rebuild, start. Use after migrations, Dockerfile changes, or config updates.

npx wtc restart 1

Show all worktrees with branch, status, URL, and ports.

npx wtc list

Copy a worktree's changed files — added, modified, and deleted — into your current branch as uncommitted changes. Skips .env and compose files, and aborts if any file it would touch has uncommitted local changes.

npx wtc promote 1

Stop all containers, remove all worktrees, prune stale Docker resources.

npx wtc clean

wtc works zero-config. For project-specific needs, create .wtcrc.json in your repo root:

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

Or use a "wtc" key in package.json. (.wtcrc.json takes precedence.)

Extra files/directories to copy from main into each worktree on start. Use for gitignored or generated files that Docker needs but aren't committed — like generated clients, local certificates, or build artifacts.

Additional env vars injected into .env. Supports ${VAR} interpolation with allocated port values. Use when env vars depend on allocated ports (e.g. VITE_API_URL).

Built-in MCP server so AI agents can manage their stack programmatically.

Claude Code (.claude/settings.json):

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

Codex:

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

cd myapp
pnpm add -D worktree-compose

git branch agent-1-auth
git branch agent-2-auth
git worktree add ../myapp-agent-1 agent-1-auth
git worktree add ../myapp-agent-2 agent-2-auth

npx wtc start
# Worktree 1: backend:28001 frontend:25174
# Worktree 2: backend:28002 frontend:25175

# Compare side by side
# http://localhost:25174  (agent 1)
# http://localhost:25175  (agent 2)

npx wtc promote 1
git add -A && git commit -m "feat: auth from agent 1"
npx wtc clean

• Node.js >= 18
• Git with worktree support
• Docker with Compose v2 (docker compose)
• docker-compose.yml with ${VAR:-default} port patterns

"No compose file found" — wtc looks in the git repo root, not the current directory.

"No extra worktrees found" — Create worktrees first: git worktree add ../my-feature my-branch

Ports not changing — Use ${VAR:-default} for host ports, not hardcoded numbers.

Stale containers — Run wtc clean, or manually: docker ps -a --filter "name=-wt-" -q | xargs docker rm -f

Issues and pull requests are welcome. Found a bug or have an idea? Open an issue — and if wtc saves you time, a ⭐ on the repo helps others find it.

MIT