worktree-compose

Zero-config Docker Compose isolation for git worktrees.

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

$npm i worktree-compose

See it in action

The Problem

Multiple developers or AI agents working in parallel on the same repo — each in a git worktree — share the same Docker Compose setup.

Without worktree-compose

Port conflicts between worktrees
Shared databases corrupt each other's data
Shared caches cause stale state
Container name collisions crash docker compose
Manual port juggling in .env files

With worktree-compose

Unique ports per worktree, automatically assigned
Isolated databases, one per worktree
Separate caches, no cross-contamination
Unique COMPOSE_PROJECT_NAME per worktree
Zero manual configuration

Features

Everything you need to run parallel worktrees without conflicts.

Zero Config

Works out of the box. Just run wtc start and your worktrees get isolated stacks.

Port Isolation

Each worktree gets unique ports via 20000 + default_port + index. No collisions, ever.

Container Isolation

Separate COMPOSE_PROJECT_NAME per worktree. Own containers, networks, and volumes.

File Sync

Compose files, Dockerfiles, and .env are synced from main before every start.

Env Injection

Port overrides are idempotently injected into .env. Your existing vars stay untouched.

MCP Server

Built-in MCP server for AI agents. Claude Code and Codex can manage stacks programmatically.

How ports are allocated

Each worktree N gets unique ports using a simple formula.

port=20000+default_port+worktree_index

20000base offset

5434postgres default

1worktree index

25435

Service	Main	Worktree 1	Worktree 2	Worktree 3
postgres	5434	25435	25436	25437
redis	6380	26381	26382	26383
backend	8000	28001	28002	28003
frontend	5173	25174	25175	25176

Commands

Six commands. That's the entire API.

wtc start [indices...]

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

$ npx wtc start 1 2

wtc stop [indices...]

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

$ npx wtc stop 1

wtc restart [indices...]

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

$ npx wtc restart 1

wtc list

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

$ npx wtc list

wtc promote <index>

Copy changed files from a worktree into your current branch as uncommitted changes. Excludes .env and compose files.

$ npx wtc promote 1

wtc clean

Stop all containers, remove all worktrees, prune stale Docker resources (networks, volumes, containers).

$ npx wtc clean

Configuration

Works zero-config out of the box. For project-specific needs, add a .wtcrc.json or a "wtc" key in your package.json.

.wtcrc.json

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

sync

Extra files or 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.

envOverrides

Additional env vars injected into .env. Supports ${VAR} interpolation with allocated port values — perfect when env vars depend on allocated ports.

Built for AI agents

Built-in MCP server so Claude Code, Codex, and other AI agents can manage worktree stacks programmatically.

.claude/settings.json

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

codex config

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

Tool	Parameters	Description
wtc_start	indices?: number[]	Start worktree stacks
wtc_stop	indices?: number[]	Stop worktree stacks
wtc_restart	indices?: number[]	Restart after migrations/config changes
wtc_list	none	List worktrees (returns JSON)
wtc_promote	index: number	Pull worktree changes into current branch
wtc_clean	none	Tear down everything