workz

Git worktree manager for AI-native development — auto-synced dependencies, environment isolation, fleet orchestration, and a lazygit-style TUI.

The Problem

git worktree add ../my-feature feature/login
cd ../my-feature
# Where's my .env? Gone.
# Where's node_modules? Gone. Time to wait for npm install again.
# Another 2GB of disk space wasted on duplicate dependencies.
# What port should this run on? Same as the other worktree?

The Fix

workz start feature/login --isolated
# .env files copied, node_modules symlinked, PORT=3000-3009 assigned, you're in. Done.

Install

# Homebrew (macOS / Linux)
brew tap rohansx/tap
brew install workz

# Cargo
cargo install workz

Or build from source:

git clone https://github.com/rohansx/workz.git
cd workz && cargo install --path .

Shell Setup

# zsh (~/.zshrc) or bash (~/.bashrc)
eval "$(workz init zsh)"

# fish (~/.config/fish/config.fish)
workz init fish | source

TUI Dashboard

Run workz with no arguments to launch the dashboard:

workz

4 panels show everything at a glance:

Panel	Shows
Worktrees	All branches, dirty state, port allocations, last commit
Fleet	Parallel AI agent tasks, running/modified/clean status
Files	Modified files for the selected worktree (M/A/D/??)
Ports	Isolated port ranges and database names

Key	Action
Tab / Shift+Tab	Cycle panels
j / k	Navigate within panel
n	New worktree
d	Delete worktree
s	Sync worktree
r	Refresh all
?	Help
q	Quit

Usage

Create a worktree

workz start feature/login            # create + auto-sync deps
workz start feature/auth --isolated  # create + assign PORT range + DB_NAME
workz start feature/api --ai         # create + launch Claude Code
workz start feature/ui --docker      # create + docker compose up

What happens:

1. Creates ../myrepo--feature-login as a git worktree
2. Symlinks node_modules, target, .venv (project-aware, not duplicated)
3. Copies .env* files into the new worktree
4. Optionally assigns isolated PORT range, DB_NAME, COMPOSE_PROJECT_NAME

List and switch

workz list              # show all worktrees with size and status
workz switch            # fzf-style fuzzy finder
workz switch login      # pre-fills query
workz status            # rich status with ports, docker, commit age

Remove a worktree

workz done                        # remove current worktree
workz done feature/login --force  # force-remove with uncommitted changes
workz done feature/login -d       # also delete the branch
workz done feature/login --cleanup-db  # also drop the isolated database

Sync existing worktrees

cd ../my-existing-worktree
workz sync   # applies symlinks, copies .env, installs deps

Clean up

workz clean                  # prune stale worktree refs
workz clean --merged         # also remove merged branches

Environment Isolation

--isolated gives each worktree its own port range, database, and compose project — no collisions between worktrees.

workz start feat/auth --isolated
# PORT=3000  PORT_END=3009  DB_NAME=feat_auth  COMPOSE_PROJECT_NAME=feat_auth

workz start feat/api --isolated
# PORT=3010  PORT_END=3019  DB_NAME=feat_api   COMPOSE_PROJECT_NAME=feat_api

All values are written to .env.local in the worktree. workz detects 14 web frameworks and writes framework-specific variables:

Framework	Extra env var
Spring Boot	SERVER_PORT
Flask	FLASK_RUN_PORT
FastAPI	UVICORN_PORT
Vite	VITE_PORT

Port ranges are allocated in aligned 10-port blocks (configurable) and tracked in ~/.config/workz/ports.json. Released automatically on workz done.

Fleet Mode

Orchestrate parallel AI agents across isolated worktrees.

# Spin up 3 Claude agents in parallel
workz fleet start \
  --task "add user authentication" \
  --task "write integration tests" \
  --task "refactor database layer" \
  --agent claude

# Watch all agents live
workz fleet status

# Run tests across all fleet worktrees
workz fleet run "cargo test"

# Merge completed work back
workz fleet merge

# Or open a PR for each
workz fleet pr --draft

# Tear it all down
workz fleet done

Load tasks from a file:

workz fleet start --from tasks.txt --agent claude

AI Agent Workflow

Launch any AI coding tool in a fresh worktree:

workz start feature/auth --ai                    # Claude Code (default)
workz start feature/ui --ai --ai-tool cursor     # Cursor
workz start feature/api --ai --ai-tool aider     # Aider
workz start feature/test --ai --ai-tool codex    # OpenAI Codex CLI
workz start feature/x --ai --ai-tool gemini      # Gemini CLI
workz start feature/y --ai --ai-tool windsurf    # Windsurf

MCP Server

workz ships a built-in MCP server so AI agents can manage worktrees autonomously.

claude mcp add workz -- workz mcp

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "workz": {
      "command": "workz",
      "args": ["mcp"]
    }
  }
}

Tools exposed

Tool	Description
workz_start	Create a worktree (supports --isolated)
workz_list	List all worktrees as JSON
workz_status	Branch, dirty state, last commit
workz_sync	Re-sync symlinks/env into a worktree
workz_done	Remove a worktree (optional force)
workz_conflicts	Detect files modified in multiple worktrees

Web Dashboard

workz serve           # localhost:7777
workz serve -p 8080   # custom port

What Gets Synced

Symlinked directories (27 dirs, project-type aware — only syncs 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
General	.direnv, .cache
IDE	.vscode, .idea, .cursor, .claude, .zed

Copied files (17 patterns): .env, .env.*, .envrc, .tool-versions, .node-version, .python-version, .ruby-version, .nvmrc, .npmrc, .yarnrc.yml, docker-compose.override.yml, .secrets, .secrets.*

Auto-install (detected from lockfiles):

Lockfile	Command
bun.lockb / bun.lock	bun install --frozen-lockfile
pnpm-lock.yaml	pnpm install --frozen-lockfile
yarn.lock	yarn install --frozen-lockfile
package-lock.json	npm ci
uv.lock	uv sync
Pipfile.lock	pipenv install
poetry.lock	poetry install
requirements.txt	pip install -r requirements.txt

Configuration

Two layers — project overrides global:

1. Global — ~/.config/workz/config.toml
2. Project — .workz.toml in repo root

[sync]
symlink = ["node_modules", "target", ".venv", "my-large-cache"]
copy = [".env*", ".envrc", "secrets.json"]
ignore = ["logs", "tmp"]

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

[isolation]
port_range_size = 10   # ports per worktree (default: 10)
base_port = 3000       # first port (default: 3000)

Zero config works out of the box for Node, Rust, Python, Go, and Java projects.

Docker Support

workz start feature/api --docker   # creates worktree + runs docker compose up -d
workz done feature/api             # stops containers + removes worktree

Supports both docker compose and podman-compose.

Requirements

• Git 2.15+
• Linux or macOS