workz

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

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

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

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 are symlinked, not duplicated
• Auto-copy env files — .env, .env.local, .envrc carried over automatically
• Fuzzy switching — zoxide-style instant navigation between worktrees
• AI-agent ready — launch Claude Code, Cursor, or VS Code in a worktree with --ai
• Shell integration — cd into worktrees automatically, just like zoxide
• Zero config — works out of the box for Node, Rust, Python, and Go projects
• Custom rules — optional .workz.toml for project-specific sync patterns
• Safe defaults — never overwrites existing files, never force-deletes dirty worktrees

Install

cargo install workz

Or build from source:

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

Shell Setup

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

eval "$(workz init zsh)"

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

workz init fish | source

This gives you a workz shell function that auto-cds into worktrees.

Usage

Create a worktree

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

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. cds you into the worktree (with shell integration)

List worktrees

workz list

  main            /home/you/myrepo
  feature-login   /home/you/myrepo--feature-login  [modified]
  bugfix-crash    /home/you/myrepo--bugfix-crash

Switch between worktrees

workz switch           # interactive picker
workz switch login     # fuzzy match — jumps to feature-login

Remove a worktree

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

Clean up stale entries

workz clean

Configuration

Create a .workz.toml in your project root to customize sync behavior:

[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 Node, Rust, Python, and Go projects.

Default sync rules

Symlinked directories (if they exist): node_modules, target, .venv, venv, .direnv, vendor

Copied files (if they exist): .env*, .envrc, .tool-versions

AI Agent Workflow

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

workz start feature/auth --ai                  # launches Claude Code
workz start feature/ui --ai --ai-tool cursor    # launches Cursor
workz start bugfix/perf --ai --ai-tool code     # launches VS Code

How It Compares

Requirements

• Git 2.15+ (for worktree support)
• A Unix-like system (Linux, macOS) or Windows with Developer Mode

License

MIT OR Apache-2.0