workz — the environment engine for agent worktrees

Your agent creates the worktree — workz makes it run.
Dependencies linked, .env copied, a unique port range, its own database and compose project. Zero config.

workz demo

Why

Claude Code, Cursor, and Codex all create git worktrees for parallel work now. But a fresh worktree is inert:

git worktree add ../feature-x feature/x && cd ../feature-x
# .env? gone.   node_modules? gone — reinstall and wait.
# dev-server port? same as every other worktree.   database? shared.

Every one of those tools ships a worktree-create hook and tells you to write the setup command yourself. workz is that command — and it's the only tool that also gives each worktree its own ports, database, and compose project.

Quickstart

# 1. install (latest — from source)
cargo install --git https://github.com/rohansx/workz
# packaged releases: `cargo install workz` · `brew install rohansx/tap/workz`

# 2. in your repo — guided setup (detects your stack, writes .workz.toml)
workz init

# 3. spin up an isolated worktree that's ready to run
workz start feature/checkout --isolated

That's it: node_modules symlinked, .env copied, PORT=3000-3009, DB_NAME and COMPOSE_PROJECT_NAME set — you're dropped into a worktree you can dev immediately, with no collisions against your other worktrees.

Use it as a hook

Let your editor/agent create worktrees natively; point its setup hook at workz sync. workz hook <host> prints the exact recipe (and --install writes it):

Host	Recipe
Cursor	`.cursor/worktrees.json` → `{ "setup-worktree": ["workz","sync","--isolated","--quiet"] }`
worktrunk	`[hooks]` → `create = "workz sync --isolated --quiet"`
Claude Code	`WorktreeCreate` hook → `workz sync --isolated --quiet "$WORKTREE_PATH"`
anything else	`workz sync --isolated --quiet <path>`

workz hook cursor --install     # writes .cursor/worktrees.json
workz hook claude               # prints the Claude Code hook to paste

--json makes sync output machine-readable; --quiet stays silent on success (warnings to stderr).

Commands

Command	Does
`workz init`	Guided setup: detect the stack, write `.workz.toml`, install a hook (`-y` for defaults)
`workz start <branch>`	Create a worktree + sync (`--isolated`, `--create-db`, `--docker`, `--ai`, `--base`)
`workz sync [path]`	Make a worktree runnable — the hook command (`--isolated`, `--json`, `--quiet`, `--no-install`)
`workz` / `workz status`	Every worktree at a glance: branch, dirty state, size, port range
`workz switch [query]`	Fuzzy-jump between worktrees
`workz list`	List worktrees (`ls`)
`workz done [branch]`	Remove a worktree (`--force`, `--delete-branch`, `--cleanup-db`)
`workz clean`	Prune stale worktrees (`--merged` removes merged branches)
`workz conflicts`	Files modified in more than one worktree — catch clashes before merge
`workz doctor`	Diagnose broken symlinks, orphaned ports, stale config (`--fix` repairs)
`workz hook <host>`	Print/install the worktree-hook recipe for a host
`workz mcp`	Run the MCP server (below)
`workz shell-init <shell>`	Shell integration for zsh/bash/fish

Environment isolation

--isolated gives each worktree its own port range, database, and compose project:

workz start feat/auth --isolated   # PORT 3000-3009  DB_NAME=feat_auth  COMPOSE_PROJECT_NAME=feat_auth
workz start feat/api  --isolated   # PORT 3010-3019  DB_NAME=feat_api   COMPOSE_PROJECT_NAME=feat_api

Values land in a managed block in .env.local, so they sit alongside — and never overwrite — your own secrets:

STRIPE_SECRET_KEY=sk_live_…            # your line, preserved

# >>> workz managed — do not edit between these markers >>>
PORT=3010
DB_NAME=feat_api
DATABASE_URL=postgres://admin:…@localhost:5432/feat_api   # derived from yours, db name swapped
COMPOSE_PROJECT_NAME=feat_api
# <<< workz managed <<<

If your .env.local already has a DATABASE_URL, workz keeps its driver/host/port/credentials and only swaps the database name.
Add --create-db to actually create the Postgres database (createdb), or --create-db --from-db dev to clone it from a template. workz done --cleanup-db drops it.
Port ranges are tracked in ~/.config/workz/ports.json and released on workz done. workz doctor --fix reclaims orphans.

What gets synced

Symlinked (project-aware — only what's relevant):

Project	Directories
Node.js	`node_modules`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.parcel-cache`, `.angular`
Rust	`target`
Python	`.venv`, `venv`, `__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`
Go	`vendor`
Java/Kotlin	`.gradle`, `build`
IDE	`.vscode`, `.idea`, `.cursor`, `.claude`, `.zed`

Copied: .env, .env.*, .envrc, .tool-versions, .npmrc, .yarnrc.yml, .secrets*, and more.
Auto-installed from the lockfile: bun / pnpm / yarn / npm ci / uv / poetry / pipenv / pip (skip with --no-install).

Symlinked node_modules breaks a Vite/Vitest/pnpm setup? Override per directory:

[sync.overrides]
node_modules = "copy"     # copy instead of symlink
".vscode"    = "ignore"   # skip entirely

Configuration

Project .workz.toml overrides global ~/.config/workz/config.toml:

[sync]
symlink_add = ["my-large-cache"]   # extend the built-in defaults
copy_add    = ["config/local.json"]
ignore_add  = ["logs"]

[sync.overrides]
node_modules = "copy"

[hooks]
post_start = "pnpm install --frozen-lockfile"
pre_done   = "docker compose down"

[isolation]
base_port       = 3000
port_range_size = 10

Zero config works out of the box for Node, Rust, Python, Go, and Java. Run workz doctor if anything looks off.

MCP server

An MCP server so agents can manage — and provision — worktrees themselves:

claude mcp add workz -- workz mcp

Tools: workz_start, workz_sync (deps + env + isolation, returns JSON), workz_list, workz_status, workz_done, workz_conflicts.

Shell setup

eval "$(workz shell-init zsh)"        # zsh / bash
workz shell-init fish | source        # fish

Adds cd-on-switch and tab completions.

MIT OR Apache-2.0 · Where workz is headed: V2.md

Why