wt — Git Worktree Manager

A CLI tool to quickly create, open, and clean up git worktrees. Designed for developers running multiple AI coding agents in parallel, each in its own worktree.

Install

Prerequisites: Python 3.9+ and uv (or pipx).

From source (development)

git clone https://github.com/gziz/wt-cli.git
cd wt-cli
uv tool install -e .
# or: pipx install -e .

This installs the wt command globally at ~/.local/bin/wt.

Shell integration (optional, for wt open --inline)

Add to your shell config so wt open --inline can change your working directory:

# ~/.bashrc or ~/.zshrc
eval "$(wt shell-init)"

# ~/.config/fish/config.fish
wt shell-init | source

Then restart your shell or source the config file.

Quick Start

cd my-repo

# Create a worktree for a branch and open it in your editor
wt open feature-auth

# List all worktrees
wt list

# Clean up worktrees that have no uncommitted changes
wt prune

Configuration

Set a default open mode so wt open always does the right thing:

wt config set open.mode code      # always open in VS Code
wt config set open.mode cursor    # always open in Cursor
wt config set open.mode inline    # always cd into the worktree

wt config get open.mode           # check current setting

Config is stored at ~/.config/wt/config.toml. You can also edit it directly:

[open]
mode = "code"

CLI flags (--code, --cursor, --inline) always override the config for a single invocation.

Commands

wt open <branch>

Creates a worktree for <branch> and opens it.

• If the branch already has a worktree, opens it directly.
• If the branch exists on the remote but not locally, creates a tracking branch.
• If the branch doesn't exist anywhere, creates a new branch from HEAD.

wt open feature-auth              # use configured mode (or auto-detect)
wt open feature-auth --code       # open in VS Code
wt open feature-auth --cursor     # open in Cursor
wt open feature-auth --inline     # cd into it (requires shell integration)
wt open feature-auth --print      # just print the path

Open mode resolution (first match wins):

Priority	Source
1	CLI flag (--code, --cursor, --inline)
2	Config file (wt config set open.mode <mode>)
3	Auto-detect (code → cursor → print path)

Where worktrees are stored (in order of priority):

Method	Example
--base flag	wt open feature -b ~/worktrees
WT_BASE env var	export WT_BASE=~/worktrees
Default	../<repo-name>-worktrees/ (sibling to your repo)

wt list

Shows all worktrees with their branch, path, and status (clean/dirty/main).

Branch      Path                                Status
-------------------------------------------------------
main        /home/user/my-repo                  main
feature-x   /home/user/my-repo-worktrees/...    clean
bugfix-42   /home/user/my-repo-worktrees/...    dirty

wt prune

Interactively removes worktrees that have no uncommitted changes ("clean" worktrees). Skips dirty ones so you don't lose work.

wt config

Get or set persistent configuration values.

wt config set <key> <value>
wt config get <key>

Available keys:

Key	Values	Description
open.mode	code, cursor, inline	Default open behavior

wt shell-init

Outputs a shell function that enables wt open --inline to change your current directory into the worktree. See Shell integration above for setup.

Use Case: Parallel AI Coding Agents

When working with AI coding agents (Copilot, Cursor, Claude, etc.), you often want multiple agents working on separate tasks simultaneously. Git worktrees let each agent have its own working directory with a clean state:

wt open agent-task-1    # Agent 1 works here
wt open agent-task-2    # Agent 2 works here
wt open agent-task-3    # Agent 3 works here

# When done, clean up all at once
wt prune

Each worktree shares the same git history but has an independent working tree — no conflicts, no stashing, no context switching.

License

MIT