worktree-compose

name	worktree-compose
description	How to run multiple git worktrees in parallel, each with isolated Docker containers and ports, using worktree-compose (`wtc`). Use when working with multi-worktree Docker setups, the `wtc` / `npx wtc` commands, per-worktree port allocation, `.wtcrc.json` config, the wtc MCP server, or promoting changes between worktrees.

Multi-Worktree Docker Compose

Run multiple git worktrees in parallel, each with isolated Docker containers and ports.

Powered by worktree-compose (wtc). Install once, globally, with npm install -g worktree-compose (it's a cross-project devtool), then drive it with npx wtc <command>.

Command	What it does
npx wtc start	Sync files, inject ports, build and start containers for all worktrees
npx wtc stop	Stop containers (docker compose down); volumes are preserved
npx wtc restart	Stop, re-sync files, re-inject env, rebuild, start (after migrations, Dockerfile or config changes)
npx wtc list (ls)	Print branch, status, URL, and ports for every worktree
npx wtc promote <index>	Copy a worktree's changed files into the current branch as uncommitted changes
npx wtc clean	Stop containers, remove all worktrees, prune stale Docker resources

All commands except promote/clean accept optional indices: npx wtc start 1, npx wtc start 1 2 3.

Worktrees come first — create one before starting a stack:

git worktree add ../myapp-feature feature-branch
npx wtc start

Port allocation

wtc auto-detects services whose host port uses the ${VAR:-default} pattern in docker-compose.yml (hardcoded ports like 8080:80 can't be isolated — wtc warns and suggests the ${VAR:-default} fix). Formula: 20000 + default_port + (worktree_index × portStride), where portStride defaults to 1.

Service	Main (default)	Worktree 1	Worktree 2
Postgres	5434	25435	25436
Redis	6380	26381	26382
Backend	8000	28001	28002
Frontend	5173	25174	25175

The table is illustrative — every value follows the formula. If your project exposes clustered default ports (e.g. mocks on 8081–8086) that collide between adjacent worktrees, wtc warns and recommends raising portStride (e.g. 100) to give each worktree its own port band.

Project naming

COMPOSE_PROJECT_NAME follows the pattern {repo}-wt-{index}-{branch}, lowercased with non-alphanumeric characters replaced by hyphens — so each worktree gets its own containers, networks, and volumes. Nothing is shared.

Configuration (optional)

wtc works zero-config. For project-specific needs, add .wtcrc.json to the repo root (or a "wtc" key in package.json; .wtcrc.json wins):

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

• sync: Extra files/dirs copied from main into each worktree on start. Use for gitignored or generated files Docker needs but that aren't committed (generated clients, local certs, build artifacts).
• envOverrides: Additional env vars injected into .env, with ${VAR} interpolation against allocated port values. Use when a var depends on an allocated port (e.g. VITE_API_URL).
• portStride: Port spacing between consecutive worktree indices (default 1). Raise it when clustered default ports would otherwise collide across worktrees.

MCP server

Agents can manage their worktree stack via MCP tools (wtc_start, wtc_stop, wtc_restart, wtc_list, wtc_promote, wtc_clean). Register it once (Claude Code .claude/settings.json):

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

See the wtc README for full setup.

How it works

docker-compose.yml uses ${VAR:-default} syntax for all host ports. On start, wtc syncs infrastructure files from main (compose file plus any include:d files, referenced Dockerfiles, and base .env), copies a fresh .env, appends allocated port overrides in an idempotent delimited block, and runs docker compose up -d --build with an isolated COMPOSE_PROJECT_NAME. Re-running start strips and rewrites the block, so it never accumulates.