wtm user guide

How wtm works beyond the first steps: its configuration, and the run module with the per-worktree isolation it rests on. They explain how the pieces fit together; the flags of each command live in wtm <command> --help and in the generated command reference.

New to wtm? Start with Getting started, then pick a setup from Recipes.

Page	What it covers
Getting started	a ten-minute tutorial: install, two worktrees running side by side, cleaning one
Recipes	complete setups: a pnpm/turbo monorepo, a docker compose app, a shared postgres, AI agents in parallel, stacked PRs
Troubleshooting	a port in use, a crashed job, the daemon's version, wtm go, exit 16, named URLs, .env drift
Configuration	config.toml, env strategies, hooks, the global config, editor autocomplete
Isolation: isolated or verbatim	how a worktree stands against its source, COMPOSE_PROJECT_NAME, adopting isolation on an older worktree, touches and foreign data
Jobs, profiles and runners	services and tasks, what run up starts, runners, the run view and -d, port checks, run ps statuses
Shared services and namespaces	one instance for the repository, a namespace per worktree, [[env]] links, what clean and prune drop
Named URLs and addressing	the run proxy, named and port URLs, url.host, the addressing mode, port 80 on macOS
How wtm run works	the job environment (WTM_*, COMPOSE_PROJECT_NAME), ports and the port check, what run init proposes, ports and addresses in a .env, compose names
run.toml reference	every key of the file, with its default
Where wtm keeps its state	the files under <git-common-dir>/wtm/ and beside the global config
Migrating to 0.28	what changed for a v0.27 user, and what to do about it

The module is opt-in: nothing here applies until wtm run init writes run.toml. Until then, the run commands that need it refuse (exit 16) and point at wtm run init.