# workz

**Zoxide for Git worktrees** — zero-config dependency syncing, fuzzy switching, and AI-agent support.

![workz demo](demo.gif)

> **What you're seeing:** `workz start` syncs deps in one shot → `workz fleet start` launches 3 Claude agents in parallel → `workz fleet status` shows a live ratatui TUI with agent PIDs, dirty files, and last commits → `workz fleet merge` brings it all back to main.

Git worktrees let you work on multiple branches simultaneously, but they leave behind your `.env` files and force you to re-install `node_modules` every time. **workz** fixes this automatically.

## The Problem

```bash
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.
```

## The Fix

```bash
workz start feature/login
# .env files copied, node_modules symlinked, you're in the worktree. Done.
```

## Features

- **Auto-symlink heavy directories** — `node_modules`, `target`, `.venv`, `vendor`, and 22+ more are symlinked, not duplicated
- **Auto-copy env files** — `.env`, `.env.local`, `.envrc`, `.npmrc`, secrets, and more carried over automatically
- **IDE config sync** — `.vscode`, `.idea`, `.cursor`, `.claude`, `.zed` symlinked automatically
- **Smart project detection** — auto-detects Node/Rust/Python/Go/Java projects and only syncs relevant dirs
- **Auto-install dependencies** — detects your package manager from lockfiles and installs if deps are missing
- **Fuzzy TUI switching** — skim-powered fzf-style fuzzy finder to jump between worktrees
- **Rich status dashboard** — `workz status` shows branch, dirty state, disk size, last commit age
- **Docker support** — `--docker` flag to auto-start containers, auto-stop on `done`
- **AI-agent ready** — launch Claude, Cursor, VS Code, Aider, Codex, Gemini, or Windsurf with `--ai`
- **Sync existing worktrees** — `workz sync` applies full setup to worktrees not created by workz
- **Shell integration** — `cd` into worktrees automatically, just like zoxide
- **Global + project config** — `~/.config/workz/config.toml` for defaults, `.workz.toml` per project
- **Zero config** — works out of the box for Node, Rust, Python, Go, and Java projects
- **Safe defaults** — never overwrites existing files, never force-deletes dirty worktrees

## Install

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

# Cargo
cargo install workz
```

Or build from source:

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

## Shell Setup

Add to your `~/.zshrc` (or `~/.bashrc`):

```bash
eval "$(workz init zsh)"
```

For fish, add to `~/.config/fish/config.fish`:

```fish
workz init fish | source
```

This gives you a `workz` shell function that auto-`cd`s into worktrees.

## Usage

### Create a worktree

```bash
workz start feature/login          # creates ../myrepo--feature-login
workz start bugfix/crash -b main   # branch from main instead of HEAD
workz start feature/auth --ai      # create + launch Claude Code
workz start feature/api --docker   # create + docker compose up
```

What happens:
1. Creates `../myrepo--feature-login` as a git worktree
2. Symlinks `node_modules`, `target`, `.venv` (if they exist in the main repo)
3. Copies `.env*` files into the new worktree
4. `cd`s you into the worktree (with shell integration)

### List worktrees

```bash
workz list
```

```
  main            /home/you/myrepo (bare)
  feature-login   /home/you/myrepo--feature-login  [modified] (142.3M)
  bugfix-crash    /home/you/myrepo--bugfix-crash (89.1M)
```

### Switch between worktrees

```bash
workz switch           # opens fzf-style fuzzy finder
workz switch login     # pre-fills query — fuzzy match to feature-login
```

### Remove a worktree

```bash
workz done                       # remove current worktree
workz done feature/login         # remove by branch name
workz done feature/login --force # force-remove even with uncommitted changes
workz done feature/login -d      # also delete the branch
```

### Sync an existing worktree

Already have worktrees created with `git worktree add`? No problem:

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

### Rich status dashboard

```bash
workz status
```

```
  main           /home/you/myrepo [modified]  342K  2 hours ago
  feature-login  /home/you/myrepo--feature-login  1.2M  5 minutes ago  [docker]
  bugfix-crash   /home/you/myrepo--bugfix-crash  890K  3 days ago
```

### Clean up stale entries

```bash
workz clean                        # prune stale worktree refs
workz clean --merged               # also remove worktrees with merged branches
workz clean --merged --base main   # specify base branch explicitly
```

## Configuration

workz supports two layers of configuration:

1. **Global** — `~/.config/workz/config.toml` (shared defaults across all repos)
2. **Project** — `.workz.toml` in your repo root (project-specific overrides)

Project config takes priority over global config.

```toml
[sync]
# Directories to symlink (shared, saves disk space)
symlink = ["node_modules", "target", ".venv", "vendor", "my-large-cache"]

# File patterns to copy into new worktrees
copy = [".env*", ".envrc", ".tool-versions", "secrets.json"]

# Patterns to never sync
ignore = ["logs", "tmp"]

[hooks]
# Run after creating a worktree
post_start = "pnpm install --frozen-lockfile"

# Run before removing a worktree
pre_done = "docker compose down"
```

Without a config file, workz uses sensible defaults that work for most projects.

### Default sync rules

**Symlinked directories** (27 dirs, project-type aware):
- **Node**: `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 configs**: `.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

workz detects your package manager from lockfiles and installs dependencies if the deps directory is missing:

| 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` |

## Docker Support

If your project has a `docker-compose.yml` (or `compose.yml`), workz can manage containers automatically:

```bash
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` (prefers podman if available).

## AI Agent Workflow

Running multiple AI agents in parallel? Each one needs its own worktree:

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

## Fleet Mode

Fleet mode orchestrates parallel AI agents across isolated worktrees in a single command.

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

# Watch all agents live — ratatui TUI with agent PIDs, dirty files, last commits
workz fleet status

# Run a command across all fleet worktrees simultaneously
workz fleet run "cargo test"

# Merge completed work back to main interactively
workz fleet merge

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

# Tear it all down
workz fleet done
```

`workz fleet status` opens a live terminal dashboard (auto-refreshes every 2s):

```
╭─ workz fleet ───────────────────────────────────── refreshed 0s ago ─╮
│  BRANCH                         TASK                  STATUS   AGENT  │
│  ──────────────────────────────────────────────────────────────────── │
│▶ fleet/add-user-authentication  add user authentication  ● run 45823  │
│  fleet/write-integration-tests  write integration tests  ● run 45867  │
│  fleet/refactor-database-layer  refactor database layer  ● run 45901  │
│                                                                        │
│  fleet/add-user-authentication                                         │
│  task    add user authentication                                       │
│  status  ● running  (agent pid 45823)                                  │
│  dirty   3 modified files                                              │
│  commit  a3b7c2d  "feat: add JWT middleware"  2 min ago                │
╰────────────────── q quit  r refresh  ↑↓ navigate ─────────────────────╯
```

Keys: `↑↓` / `jk` to navigate, `r` to force refresh, `q` / `Esc` to quit.
Piping (`workz fleet status | grep running`) falls back to plain-text output automatically.

## MCP Server

workz ships a built-in MCP server so AI agents can manage worktrees themselves — no human needed.

### Setup

```bash
claude mcp add workz -- workz mcp
```

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

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

### Tools exposed to agents

| Tool | Description |
|------|-------------|
| `workz_start` | Create a worktree with auto-synced deps and env |
| `workz_list` | List all worktrees as structured JSON |
| `workz_status` | Rich status: branch, dirty state, last commit |
| `workz_sync` | Sync symlinks/env into an existing worktree |
| `workz_done` | Remove a worktree (with optional force) |
| `workz_conflicts` | Detect files modified in multiple worktrees |

Once configured, Claude Code and other MCP-compatible agents can create and manage worktrees autonomously without any manual setup.

## How It Compares

| Feature | workz | worktrunk | gwq | fracture | branchlet |
|---|---|---|---|---|---|
| Auto-symlink deps | yes | config required | no | no | no |
| Auto-copy .env | yes | config required | config required | yes | no |
| Smart project detection | yes | no | no | no | no |
| Auto-install deps | yes | no | no | no | no |
| Fuzzy TUI (skim/fzf) | yes | no | yes | no | no |
| Docker integration | yes | no | no | no | no |
| Shell cd integration | yes | no | no | no | no |
| AI agent launch | yes | yes | no | no | no |
| Global + project config | yes | no | no | no | no |
| Zero config | yes | no | no | yes | no |
| Single binary | yes | yes | yes | ? | no (npm) |

## Requirements

- Git 2.15+ (for worktree support)
- A Unix-like system (Linux, macOS)

## License

MIT OR Apache-2.0