{"_id":"worktree-compose","_rev":"6-9927fef2d2aa7902a628ba834a3b4f88","name":"worktree-compose","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"worktree-compose","version":"0.1.0","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp"],"license":"MIT","_id":"worktree-compose@0.1.0","maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"bin":{"wtc":"dist/cli.js","worktree-compose":"dist/cli.js"},"dist":{"shasum":"512eeb71031292f83a8fe8a1d75c9ecb482b3a46","tarball":"https://registry.npmjs.org/worktree-compose/-/worktree-compose-0.1.0.tgz","fileCount":48,"integrity":"sha512-mno0JdE1kxkL2zZQj9wFM2Vk+XWw+/IIqLJY1zSnU/lyAtIvvwMQDIbbvhvJWjEhDBd2THDO2KUFhso3FskfuA==","signatures":[{"sig":"MEUCIQD+MUkchz14saRflaBaopoo6+KQlLR2JjKfi/MX0TIjgwIgQeyG7yfC04oYtTnFEm1BC1Z8pC7w4LAyUOEpxLQiy5M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61509},"type":"module","engines":{"node":">=18"},"gitHead":"cd0bb6efa2a2598366d0fab3019b581cc9c8c1eb","scripts":{"dev":"tsx src/cli.ts","test":"NODE_OPTIONS='--experimental-vm-modules' jest --coverage","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"levw","email":"abdelraahmanmostafa@gmail.com"},"_npmVersion":"10.9.2","description":"Zero-config Docker Compose isolation for git worktrees","directories":{},"_nodeVersion":"22.15.0","dependencies":{"zod":"^3.24.4","yaml":"^2.8.0","chalk":"^5.4.1","commander":"^14.0.0","cli-table3":"^0.6.5","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jest":"^29.7.0","ts-jest":"^29.3.4","typescript":"^5.8.3","@types/jest":"^29.5.14","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/worktree-compose_0.1.0_1771851495865_0.8841681298209596","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"worktree-compose","version":"0.1.2","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp"],"license":"MIT","_id":"worktree-compose@0.1.2","maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"homepage":"https://github.com/LevwTech/worktree-compose#readme","bugs":{"url":"https://github.com/LevwTech/worktree-compose/issues"},"bin":{"wtc":"dist/cli.js","worktree-compose":"dist/cli.js"},"dist":{"shasum":"ae379075fdc35f1aa67118f3af3773bdfb0747a8","tarball":"https://registry.npmjs.org/worktree-compose/-/worktree-compose-0.1.2.tgz","fileCount":48,"integrity":"sha512-ICgHWogMdVeIzJ3osaEmO7N4xKeyij2vcrFxdDDU/lCx2rQqtzQp4pFHo01mN7ZEu9pm5/pxFj0RiPweMUhMJA==","signatures":[{"sig":"MEUCIQCuPuOA5NZY96LUCrKlv2wS0o0vuhvivVvFPOpPWg3KDwIgJMvGCkfzi6XtWHD9vo+cwpF6+0h8toDpTQYwjVIJ29s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50872},"type":"module","engines":{"node":">=18"},"gitHead":"48e328c83bf689a4482d6e011505f663a9746bda","scripts":{"dev":"tsx src/cli.ts","test":"NODE_OPTIONS='--experimental-vm-modules' jest --coverage","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"levw","email":"abdelraahmanmostafa@gmail.com"},"repository":{"url":"git+https://github.com/LevwTech/worktree-compose.git","type":"git"},"_npmVersion":"10.9.2","description":"Zero-config Docker Compose isolation for git worktrees","directories":{},"_nodeVersion":"22.15.0","dependencies":{"zod":"^3.24.4","yaml":"^2.8.0","chalk":"^5.4.1","commander":"^14.0.0","cli-table3":"^0.6.5","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jest":"^29.7.0","ts-jest":"^29.3.4","typescript":"^5.8.3","@types/jest":"^29.5.14","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/worktree-compose_0.1.2_1771852302690_0.8025095032743181","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"worktree-compose","version":"0.1.3","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp"],"license":"MIT","_id":"worktree-compose@0.1.3","maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"homepage":"https://github.com/LevwTech/worktree-compose#readme","bugs":{"url":"https://github.com/LevwTech/worktree-compose/issues"},"bin":{"wtc":"dist/cli.js","worktree-compose":"dist/cli.js"},"dist":{"shasum":"d0c5ff1bea48aefe6612c6d49b4498a6019a915d","tarball":"https://registry.npmjs.org/worktree-compose/-/worktree-compose-0.1.3.tgz","fileCount":49,"integrity":"sha512-se3f2PYZFLd0V6rWbIR3sJpLEwCngRdLIluEHQIiuEfE+V1MdLGmh+iyYXCp61Gz0SblXIyGyVetp36GBoUmWw==","signatures":[{"sig":"MEUCIFveiv7FN0ehLdOfkZSWGUzTMKtd4jphE5sJtoTUHgCCAiEA6/O3eAsIPKjHbEeeZGgan2i73BEAVLWwhQu9HOPeBXw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":52073},"type":"module","engines":{"node":">=18"},"gitHead":"0fa7a8f98c4b2ef85eb2f3ef6f5523214102e8ac","scripts":{"dev":"tsx src/cli.ts","test":"NODE_OPTIONS='--experimental-vm-modules' jest --coverage","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"levw","email":"abdelraahmanmostafa@gmail.com"},"repository":{"url":"git+https://github.com/LevwTech/worktree-compose.git","type":"git"},"_npmVersion":"10.9.2","description":"Zero-config Docker Compose isolation for git worktrees","directories":{},"_nodeVersion":"22.15.0","dependencies":{"zod":"^3.24.4","yaml":"^2.8.0","chalk":"^5.4.1","commander":"^14.0.0","cli-table3":"^0.6.5","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jest":"^29.7.0","ts-jest":"^29.3.4","typescript":"^5.8.3","@types/jest":"^29.5.14","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/worktree-compose_0.1.3_1771856832816_0.670303059378953","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"worktree-compose","version":"0.1.4","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp"],"license":"MIT","_id":"worktree-compose@0.1.4","maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"homepage":"https://github.com/LevwTech/worktree-compose#readme","bugs":{"url":"https://github.com/LevwTech/worktree-compose/issues"},"bin":{"wtc":"dist/cli.js","worktree-compose":"dist/cli.js"},"dist":{"shasum":"effdb64c149bdbfbeb7a98aded6185fceb63161d","tarball":"https://registry.npmjs.org/worktree-compose/-/worktree-compose-0.1.4.tgz","fileCount":49,"integrity":"sha512-bRkYW2eGxDIxRbl3hb4qLIGGqJjWHYt0L/TjLZ+9pK9U2PGRReN+HIoLOSBBq7rcnTqsQdQU/r6nfzMwX95U6g==","signatures":[{"sig":"MEUCIG56otNErZIZ82OI7ZsDwHBs6h3FAYc7/USoXHukkKznAiEA7awPCQb/6fPB+gaJVAPGi5NgkiRbix0E0Tni1W1vuPY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":52083},"type":"module","engines":{"node":">=18"},"gitHead":"bd1818154463276b63b9983f54ef1122f0d52239","scripts":{"dev":"tsx src/cli.ts","test":"NODE_OPTIONS='--experimental-vm-modules' jest --coverage","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"levw","email":"abdelraahmanmostafa@gmail.com"},"repository":{"url":"git+https://github.com/LevwTech/worktree-compose.git","type":"git"},"_npmVersion":"10.9.2","description":"Zero-config Docker Compose isolation for git worktrees","directories":{},"_nodeVersion":"22.15.0","dependencies":{"zod":"^3.24.4","yaml":"^2.8.0","chalk":"^5.4.1","commander":"^14.0.0","cli-table3":"^0.6.5","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jest":"^29.7.0","ts-jest":"^29.3.4","typescript":"^5.8.3","@types/jest":"^29.5.14","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/worktree-compose_0.1.4_1771862932519_0.5698627442711974","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"worktree-compose","version":"0.2.0","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp"],"license":"MIT","_id":"worktree-compose@0.2.0","maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"homepage":"https://github.com/mostafasudo/worktree-compose#readme","bugs":{"url":"https://github.com/mostafasudo/worktree-compose/issues"},"bin":{"wtc":"dist/cli.js","worktree-compose":"dist/cli.js"},"dist":{"shasum":"a58d16144467816253bd7b2e0325849b0ff7d422","tarball":"https://registry.npmjs.org/worktree-compose/-/worktree-compose-0.2.0.tgz","fileCount":49,"integrity":"sha512-Tt/4cTOWf4rkfbKJ1B/H9f6Wmt8Cs3H4EmODmHIr++jqW1F0ajp4/dtpRxJ1REEo48HxARnc9JhOgUUcKFwSBw==","signatures":[{"sig":"MEYCIQCPx1rVKW/aWp6C/cH4WZMyIynljQQqVtceYS70tgVQDAIhAJ+Ba5PmdnRwY3k+GUA4X8a9/ShX8KuBYqZTeBg+uET3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68116},"type":"module","_from":"file:worktree-compose-0.2.0.tgz","engines":{"node":">=18"},"scripts":{"dev":"tsx src/cli.ts","test":"NODE_OPTIONS='--experimental-vm-modules' jest --coverage","build":"tsc","release":"set -a && . ./.env && set +a && pnpm publish --no-git-checks"},"_npmUser":{"name":"levw","email":"abdelraahmanmostafa@gmail.com"},"_resolved":"/private/var/folders/t7/7td0y11n219fy3g87clfnv_r0000gn/T/b08c8467da931124a0f62616bcff2bc9/worktree-compose-0.2.0.tgz","_integrity":"sha512-Tt/4cTOWf4rkfbKJ1B/H9f6Wmt8Cs3H4EmODmHIr++jqW1F0ajp4/dtpRxJ1REEo48HxARnc9JhOgUUcKFwSBw==","repository":{"url":"git+https://github.com/mostafasudo/worktree-compose.git","type":"git"},"_npmVersion":"10.9.2","description":"Zero-config Docker Compose isolation for git worktrees","directories":{},"_nodeVersion":"22.15.0","dependencies":{"zod":"^3.24.4","yaml":"^2.8.0","chalk":"^5.4.1","commander":"^14.0.0","cli-table3":"^0.6.5","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jest":"^29.7.0","ts-jest":"^29.3.4","typescript":"^5.8.3","@types/jest":"^29.5.14","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/worktree-compose_0.2.0_1782469884385_0.15923115862641857","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"_id":"worktree-compose@1.0.0","bin":{"wtc":"dist/cli.js","worktree-compose":"dist/cli.js"},"bugs":{"url":"https://github.com/mostafasudo/worktree-compose/issues"},"dist":{"shasum":"e8a9ebc39510be25b88e7a567457e19d97e0164b","tarball":"https://registry.npmjs.org/worktree-compose/-/worktree-compose-1.0.0.tgz","fileCount":101,"integrity":"sha512-xQSXSHCm5nBbZnzkBR86F1/Cmue59XQoeAuLh5SNe4xscWuY8/TeT+UvIVAU2VgAG/uBJ0Q/AQd7PnOPkjYqJQ==","signatures":[{"sig":"MEQCIERg/eEK6pcBjiciybJ1AsktIwi8T2luTzeCxww0Xvg2AiA5PuknmGrLcGKOjPn3ohA2vjwb5xu5MSlW1wIG7XuJCA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC9dP9We0yX7hCtqvuVqafZ7jF/PQM+bcoq+1VuzKsxTAIgRaRLBGpzkixQz1AlKNmQOX0GQAqXdVjIksu6a2ExzlM="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/worktree-compose@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":374291},"name":"worktree-compose","type":"module","engines":{"node":">=20"},"gitHead":"1aad0b05cbb465fb284b1e3637ee11e0c9d592a5","license":"MIT","scripts":{"dev":"tsx src/cli.ts","test":"NODE_OPTIONS='--experimental-vm-modules' jest --coverage","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"version":"1.0.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"32d016b7-19d0-4bc8-be57-1a15cd59c314"}},"homepage":"https://www.worktree-compose.com","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp","podman"],"repository":{"url":"git+https://github.com/mostafasudo/worktree-compose.git","type":"git"},"_npmVersion":"11.21.1","description":"Zero-config Docker Compose isolation for git worktrees","directories":{},"maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"zod":"^3.25.0","yaml":"^2.8.0","chalk":"^5.4.1","commander":"^14.0.0","cli-table3":"^0.6.5","@modelcontextprotocol/sdk":"^1.26.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","jest":"^29.7.0","ts-jest":"^29.3.4","typescript":"^5.8.3","@types/jest":"^29.5.14","@types/node":"^22.15.21"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/worktree-compose_1.0.0_1792828705036_0.811600480953572"}}},"time":{"created":"2026-02-23T12:58:15.865Z","modified":"2026-10-24T07:58:25.527Z","0.1.0":"2026-02-23T12:58:16.017Z","0.1.2":"2026-02-23T13:11:42.844Z","0.1.3":"2026-02-23T14:27:12.961Z","0.1.4":"2026-02-23T16:08:52.657Z","0.2.0":"2026-06-26T10:31:24.580Z","1.0.0":"2026-10-24T07:58:25.140Z"},"bugs":{"url":"https://github.com/mostafasudo/worktree-compose/issues"},"license":"MIT","homepage":"https://www.worktree-compose.com","keywords":["git","worktree","docker","compose","isolation","parallel","development","mcp","podman"],"repository":{"url":"git+https://github.com/mostafasudo/worktree-compose.git","type":"git"},"description":"Zero-config Docker Compose isolation for git worktrees","maintainers":[{"name":"levw","email":"abdelraahmanmostafa@gmail.com"}],"readme":"
\n\n\"worktree-compose\n\n# worktree-compose · `wtc`\n\n### Zero-config Docker Compose isolation for git worktrees\n\nEvery worktree gets its own ports, database, cache, and containers — **automatically**.\n\n[![npm version](https://img.shields.io/npm/v/worktree-compose?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/worktree-compose)\n[![downloads](https://img.shields.io/npm/dm/worktree-compose?color=cb3837)](https://www.npmjs.com/package/worktree-compose)\n[![node](https://img.shields.io/node/v/worktree-compose?color=339933&logo=node.js&logoColor=white)](https://nodejs.org)\n[![license](https://img.shields.io/npm/l/worktree-compose?color=blue)](https://github.com/mostafasudo/worktree-compose/blob/main/LICENSE)\n[![DevHunt](https://img.shields.io/badge/DevHunt-%231%20Product%20of%20the%20Week-ff6154)](https://devhunt.org/tool/worktree-compose)\n\n**[worktree-compose.com](https://www.worktree-compose.com)** · [Changelog](https://github.com/mostafasudo/worktree-compose/blob/main/CHANGELOG.md) · [Agent skill](https://github.com/mostafasudo/worktree-compose/blob/main/SKILL.md) · [GitHub](https://github.com/mostafasudo/worktree-compose)\n\n\"worktree-compose\n\nThe full wtc workflow: an isolated Docker stack per worktree, four AI agents building in parallel, compared live on their own ports — then promote the winner and clean up. Watch the video.\n\n
\n\n```bash\nnpm install -g worktree-compose\n```\n\n```\nwtc list\n\n┌───────┬──────────────┬────────┬────────────────────────┬────────────────────────────────────────────────────────────┐\n│ Index │ Branch │ Status │ URL │ Ports │\n├───────┼──────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ - │ main │ - │ - │ postgres:5434 backend:8000 frontend:5173 │\n├───────┼──────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ 1 │ feature-auth │ up │ http://localhost:25174 │ POSTGRES_PORT=25435 BACKEND_PORT=28001 FRONTEND_PORT=25174 │\n├───────┼──────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ 2 │ fix-billing │ exited │ http://localhost:25175 │ POSTGRES_PORT=25436 BACKEND_PORT=28002 FRONTEND_PORT=25175 │\n└───────┴──────────────┴────────┴────────────────────────┴────────────────────────────────────────────────────────────┘\n```\n\n> **Type `wtc`, not `npx wtc`.** An unrelated npm package is named `wtc`, so without the global install `npx wtc` downloads and runs that package instead. For a one-off run without installing, use `npx worktree-compose ` (for example `npx worktree-compose list`).\n\n## Contents\n\n- [Why wtc?](#why-wtc)\n- [How is this different from `docker compose -p`?](#how-is-this-different-from-docker-compose--p)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Selecting worktrees](#selecting-worktrees)\n- [Preparing your compose file](#preparing-your-compose-file)\n- [Monorepos & custom env files](#monorepos--custom-env-files)\n- [How It Works](#how-it-works) — [stable identity](#stable-worktree-identity), [ports](#port-allocation), [project names](#container-isolation-and-compose_project_name), [file sync](#file-sync), [env files](#env-files)\n- [Commands](#commands) — [what each one does to your data](#what-each-command-does-to-your-data)\n- [Configuration (Optional)](#configuration-optional)\n- [Docker, Podman, OrbStack, Colima](#docker-podman-orbstack-colima)\n- [MCP Server](#mcp-server)\n- [Agent Skill](#agent-skill)\n- [Full Example](#full-example)\n- [Upgrading from 0.2](#upgrading-from-02)\n- [Requirements](#requirements)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why wtc?\n\nSpin up multiple developers or AI agents on the same repo — each in its own [git worktree](https://git-scm.com/docs/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.\n\n`wtc` reads your existing compose file and turns every worktree into a fully isolated, side-by-side environment — unique host ports, separate containers, networks, and volumes — with **zero configuration**.\n\n- ⚡ **Zero config** — reads your existing `docker-compose.yml` / `compose.yaml`, no new files required\n- 🔌 **Automatic ports** — unique, collision-free host ports per worktree\n- 📦 **Full isolation** — separate containers, networks, and volumes for each stack\n- 📌 **Stable identity** — a worktree keeps its index, ports, and project name; removing one never renumbers the others\n- 🧪 **True side-by-side** — run `N` stacks at once and compare them in the browser\n- 🔄 **One-command promote** — pull a worktree's changes back into your branch\n- 🐳 **Docker or Podman** — Docker Compose v2, Podman, OrbStack, Colima\n- 🩺 **`wtc doctor`** — finds what would break isolation before it bites\n- 🤖 **Built-in MCP server + agent skill** — let AI agents start, stop, and manage their own stacks\n\n\n\n\n
Without wtcWith wtc
\n\n```bash\ngit worktree add ../app-feat feat\n# hand-pick non-colliding host ports\n# edit ../app-feat/.env per service\n# copy compose file + Dockerfiles over\ndocker compose -p app-feat up -d --build\n# ...remember to tear it all down later\n```\n\n\n\n```bash\ngit worktree add ../app-feat feat\nwtc start\n\n# ...and when you're done:\nwtc clean\n```\n\n
\n\n## How is this different from `docker compose -p`?\n\n`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, remember which project belongs to which worktree, and tear everything down yourself. `wtc` builds on that same project-name isolation and automates the rest: collision-free **port allocation**, a **stable index and project name** per worktree, per-worktree **env file injection** (including `COMPOSE_PROJECT_NAME`, so plain `docker compose` in the worktree hits the right stack), infra-file **sync**, one-command **`promote`**, safe **cleanup**, and a built-in **MCP server** so AI agents can drive it all themselves.\n\n## Quick Start\n\n```bash\n# 1. Install once, globally\nnpm install -g worktree-compose\n\n# 2. Create a worktree for some parallel work\ngit worktree add -b feature ../myapp-feature\n\n# 3. Boot an isolated stack for it (\".\" = the worktree you're in)\ncd ../myapp-feature\nwtc start .\n\n# 4. See every stack, its status, URL, and ports\nwtc list\n\n# 5. Something off? Ask the doctor\nwtc doctor\n```\n\n`wtc` works from the main checkout or from any worktree: it always reads the compose file, config, and env files from the main checkout.\n\n## Usage\n\n```bash\nwtc start # start every worktree's stack\nwtc start . # just the worktree you're in\nwtc start 1 fix-billing # by index, branch, directory name, or path\nwtc start --no-build # skip the image rebuild\nwtc start --env .env.development --workspace server # monorepo env files\n\nwtc list # status, URL, and ports (alias: wtc ls; --json for scripts)\nwtc stop 1 # stop the containers; data is kept and start resumes them\nwtc restart . # re-sync files and env, recreate what changed\n\nwtc promote fix-billing # copy a worktree's changes into the current checkout\n\nwtc prune # tear down stacks of worktrees you already deleted\nwtc clean --dry-run # preview the full cleanup\nwtc clean # tear down every stack (deletes volumes), remove worktrees that hold no work\n\nwtc doctor # check git, engine, ports, isolation, orphans\nwtc skill --install # install the agent skill\nwtc mcp # MCP server for AI agents (stdio)\n```\n\n## Selecting worktrees\n\n`start`, `stop`, and `restart` take any number of worktrees (none means all); `promote` takes exactly one. Each one can be given as:\n\n| Selector | Example | Matches |\n|----------|---------|---------|\n| index | `2` | the worktree's stable index (the `Index` column of `wtc list`) |\n| branch | `fix-billing` | the branch checked out in the worktree |\n| directory name | `myapp-fix-billing` | the basename of the worktree's directory |\n| path | `../myapp-fix-billing` | a path, resolved against the current directory (symlinks such as macOS `/tmp` are followed) |\n| `.` | `.` | the worktree that contains the current directory |\n\n- A name that matches several worktrees (say, two directories with the same basename in different places) is an error listing them; use the index instead.\n- A number is an index, unless it also names a *different* worktree (a branch or directory called `2`). Then `wtc` refuses and asks for the branch, the directory name, or a path — the message suggests one that works from where you are (e.g. `../2`).\n- Through MCP, a JSON number is always an index; a string follows the rules above.\n\n## Preparing your compose file\n\n`wtc` looks for `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml` (in that order) at the root of the main checkout.\n\nFor `wtc` to isolate a service's port, the host port must use the `${VAR:-default}` pattern, with an upper-case variable name:\n\n```yaml\n# wtc CAN isolate this\nports:\n - \"${BACKEND_PORT:-8000}:8000\"\n\n# wtc CANNOT isolate this (hardcoded)\nports:\n - \"8080:8080\"\n```\n\nIf `wtc` finds hardcoded ports, it warns you and suggests the fix:\n\n```\n⚠ Service \"nginx\" uses a raw port mapping (8080:80). To enable port isolation, change it to: \"${NGINX_PORT:-8080}:80\"\n```\n\n### Supported port formats\n\n```yaml\n# Standard\n- \"${BACKEND_PORT:-8000}:8000\"\n\n# Same var for host and container\n- \"${FRONTEND_PORT:-5173}:${FRONTEND_PORT:-5173}\"\n\n# IP-bound\n- \"127.0.0.1:${API_PORT:-3000}:3000\"\n\n# With protocol\n- \"${BACKEND_PORT:-8000}:8000/tcp\"\n\n# Multiple ports per service\n- \"${BACKEND_PORT:-8000}:8000\"\n- \"${DEBUG_PORT:-9229}:9229\"\n\n# Long-form syntax\n- target: 8000\n published: \"${BACKEND_PORT:-8000}\"\n protocol: tcp\n```\n\n### Settings that break isolation\n\n`wtc start` and `wtc doctor` warn about compose settings that make worktree stacks collide or share data (`wtc list` only prints how many there are):\n\n- **`container_name: db`** — every stack would use the same container name, so the second one fails to start. Remove it, or make it per-stack: `container_name: ${COMPOSE_PROJECT_NAME:-myapp}-db`.\n- **Top-level volumes or networks with a fixed `name:` or `external: true`** — every stack shares them. A `name:` that contains `${COMPOSE_PROJECT_NAME}` is per-stack and fine.\n- **Hardcoded host ports** — see above.\n- **Cross-worktree port collisions** — see [`portStride`](#clustered-default-ports-and-portstride).\n\n### Included compose files\n\nIf your compose file pulls in others via the top-level [`include:`](https://docs.docker.com/reference/compose-file/include/) directive, `wtc` follows them recursively — services defined in included files get the same port isolation as top-level ones, and the included files are copied into each worktree alongside the main one.\n\n```yaml\ninclude:\n - ./db/compose.yml\n - path: ./services/api/compose.yml\n```\n\nBuild contexts in an included file resolve relative to that file's own directory, just as Docker Compose does. (Included files that live outside the repo still have their ports isolated, but aren't copied into the worktree.)\n\n## Monorepos & custom env files\n\nIn a monorepo, local env files usually live next to each app (`apps/server/.env.development`) instead of at the repo root, and the filename isn't always `.env`. Use `envFile` plus workspace selectors to keep every worktree's env files consistent:\n\n```bash\n# Copy + inject apps/server/.env.development and apps/homepage/.env.development\n# into the worktree, in addition to the root env file\nwtc start --env .env.development --workspace server --workspace homepage\n```\n\nOr make it the project default in `.wtcrc.json`:\n\n```json\n{\n \"$schema\": \"https://unpkg.com/worktree-compose/wtc.schema.json\",\n \"envFile\": \".env.development\",\n \"workspaces\": [\"server\", \"homepage\"],\n \"workspaceEnvOverrides\": {\n \"server\": {\n \"DATABASE_URL\": \"postgresql://postgres:postgres@localhost:${POSTGRES_PORT}/postgres\"\n }\n }\n}\n```\n\nHow workspace selection works:\n\n- Workspaces come from `package.json#workspaces` (npm/bun/yarn) or `pnpm-workspace.yaml#packages`. Only directories with a `package.json` count. In a repo that declares no workspaces, `--workspace server` looks for a `package.json` in `server`, `apps/server`, `packages/server`, or `libs/server`.\n- `--workspace` matches by package **name**, directory name, or repo-relative path, and may be repeated. On the command line it replaces the configured `workspaces` for that run; `--env` likewise replaces `envFile`.\n- The **repo root is always processed** — docker compose interpolates `${POSTGRES_PORT:-5434}` from the root env file, so skipping it would break port isolation. Only the root env file gets `COMPOSE_PROJECT_NAME`.\n- Every target gets the allocated port variables. A selected workspace with no env file (and no `.env.example`) is skipped with a warning.\n- `workspaceEnvOverrides` keys match a workspace by package name, then by directory name (only when no other workspace shares it), then by repo-relative path.\n- `restart` checks `--env` and `--workspace` before stopping anything, so a typo never leaves stacks stopped.\n\n> **Why `--env`, not `--env-file`?** Node.js intercepts `--env-file` in its own argv parsing — even after the script path — so the flag never reaches `wtc`. `--env` is the safe spelling; the config key stays `envFile`. It must be a bare filename such as `.env.development`.\n\n## How It Works\n\n### Stable worktree identity\n\nThe first time `wtc` acts on a worktree (`start`, `stop`, …), it records the worktree's **index** (which decides its ports) and its **compose project name** in `.git/wtc/state.json`: inside the git directory every worktree shares, never committed. From then on they don't change. `wtc list`, `wtc doctor`, and dry runs only read: they show the identity a new worktree will get without recording it.\n\n- **Removing a worktree never renumbers the others.** (0.2 derived the index from the position in `git worktree list`, so removing worktree 1 silently moved worktree 2 onto new ports and a new project, orphaning its running stack — [#9](https://github.com/mostafasudo/worktree-compose/issues/9).)\n- **A new worktree gets the lowest index no record holds.**\n- **Renaming the branch keeps the project name**, and **`git worktree move` keeps the index, ports, and project**: `wtc` keeps an id in the worktree's git admin directory (`.git/worktrees//wtc-id`), which a move keeps and `git worktree remove` deletes. Restart a moved worktree so bind mounts follow the new path.\n- **A worktree you delete becomes an orphan.** After `git worktree remove` or `rm -rf`, `wtc list` shows it as `(removed)`. Its index stays reserved, because its stack may still be running on those ports, until `wtc prune` (or `wtc clean`) tears the stack down and forgets it.\n- **A worktree git still lists is never an orphan**, even when `wtc` can't start it: a [locked](https://git-scm.com/docs/git-worktree#_commands) worktree whose directory is missing (an unmounted drive) shows as `(locked, missing on disk)` and keeps its index, record, and stack until it is back; `prune` and `clean` leave it alone.\n\n```\ngit worktree remove ../myapp-spike-cache\ngit worktree add -b docs ../myapp-docs\nwtc list\n\n┌───────┬───────────────────────┬────────┬────────────────────────┬────────────────────────────────────────────────────────────┐\n│ Index │ Branch │ Status │ URL │ Ports │\n├───────┼───────────────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ - │ main │ - │ - │ postgres:5434 backend:8000 frontend:5173 │\n├───────┼───────────────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ 1 │ feature-auth │ up │ http://localhost:25174 │ POSTGRES_PORT=25435 BACKEND_PORT=28001 FRONTEND_PORT=25174 │\n├───────┼───────────────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ 2 │ fix-billing │ exited │ http://localhost:25175 │ POSTGRES_PORT=25436 BACKEND_PORT=28002 FRONTEND_PORT=25175 │\n├───────┼───────────────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ 3 │ spike-cache (removed) │ up │ - │ POSTGRES_PORT=25437 BACKEND_PORT=28003 FRONTEND_PORT=25176 │\n├───────┼───────────────────────┼────────┼────────────────────────┼────────────────────────────────────────────────────────────┤\n│ 4 │ docs │ down │ http://localhost:25177 │ POSTGRES_PORT=25438 BACKEND_PORT=28004 FRONTEND_PORT=25177 │\n└───────┴───────────────────────┴────────┴────────────────────────┴────────────────────────────────────────────────────────────┘\n(removed) = the worktree is gone but its stack/record remains. Run 'wtc prune' to tear it down.\n```\n\n**Coming from 0.2?** On the first run, `wtc` gives existing worktrees the same positional indices 0.2 used, and a worktree whose 0.2 stack is still running adopts that stack's index and project (matched by the directory compose ran in). Running stacks are picked up, not duplicated. If `state.json` is ever lost or unreadable, it is rebuilt the same way (an unreadable file is first moved aside as `state.json.bak-