wtx

Per-worktree Docker Compose isolation for parallel development (humans and AI agents).

Each git worktree gets its own compose project, host ports, container names, and volumes — so several worktrees of the same repo (or different repos) run their postgres/redis/dev-server stacks side by side without collisions. The main checkout is untouched: there, wtx up is a passthrough to docker compose up -d and your committed ports keep working.

Install

npm i -g github:abtion/wtx

Requires node >= 22, git, and Docker Compose >= 2.24 (for !override).

Per-repo setup (once)

Commit a .wtx.yml declaring which env vars your app needs, with port placeholders. wtx refuses to run without it — no magic, no guessing.

# .wtx.yml
env:
  DATABASE_SERVER: postgres://postgres@localhost:${wtx.postgres.5432}
  REDIS_URL: redis://localhost:${wtx.redis.6379}
  PORT: ${wtx.app}
  SHAKAPACKER_DEV_SERVER_PORT: ${wtx.app.assets}

Placeholders:

• ${wtx.<service>.<containerPort>} — the allocated host port for a compose service's published port (e.g. ${wtx.postgres.5432}).
• ${wtx.app} — an allocated host port for your app process (runs on the host).
• ${wtx.app.<name>} — additional named host ports (asset server, etc.).

Use

cd .worktrees/fix-login
wtx up                 # isolated stack up; prints allocated ports
wtx exec bin/setup     # run anything with DATABASE_SERVER/PORT/... injected
wtx exec bin/rails s   # dotenv never overrides real env vars, so these win
wtx env                # print `export` lines (for eval / direnv)
wtx status             # ports + containers for this worktree
wtx down               # stop (keeps volumes)
wtx clean              # stop + delete volumes and state
wtx gc                 # sweep stacks whose worktree was deleted

How it works

• Compose project name: wtx-<repo>-<worktree>-<hash-of-path> — unique across worktrees and across repos.
• Ports: deterministic hash of the project name into 42000–48999, probed for availability, then persisted in ~/.wtx/ so they stay stable across restarts. All published ports in your compose file are remapped (bound to 127.0.0.1), even ones not referenced in .wtx.yml.
• Override file: generated into ~/.wtx/overrides/ — your repo's compose file is never modified, and nothing git-ignored needs to be added to your repo.
• Cleanup: every container is labeled with its worktree path; wtx gc removes stacks (and volumes) whose path no longer exists.

Agents

Add to your project's CLAUDE.md / agent instructions:

When working in a git worktree, start backing services with `wtx up` and run
all app commands through `wtx exec <cmd>` so ports and databases don't collide
with other worktrees. Run `wtx clean` before deleting the worktree.