# 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
```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` 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
```bash
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
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
```
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
feature-login /home/you/myrepo--feature-login [modified]
bugfix-crash /home/you/myrepo--bugfix-crash
```
### Switch between worktrees
```bash
workz switch # interactive picker
workz switch login # fuzzy match — jumps 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
```
### Clean up stale entries
```bash
workz clean
```
## Configuration
Create a `.workz.toml` in your project root to customize sync behavior:
```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 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:
```bash
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
| Auto-symlink deps | yes | config required | no | no | no |
| Auto-copy .env | yes | config required | config required | yes | no |
| Fuzzy switching | yes | no | yes | no | no |
| Shell cd integration | yes | no | no | no | no |
| AI agent launch | yes | yes | no | no | no |
| Zero config | yes | no | no | yes | no |
| Single binary | yes | yes | yes | ? | no (npm) |
| Custom config | yes | yes | yes | no | yes |
## Requirements
- Git 2.15+ (for worktree support)
- A Unix-like system (Linux, macOS) or Windows with Developer Mode
## License
MIT OR Apache-2.0