wtm

Worktree Manager (wtm) 🪵

Seamless Git worktree orchestration for humans and AI agents alike.

wtm keeps every active branch in a tidy .wtm/ playground with one-line commands, so you can spin up review branches, isolate experiments, and hand off context to AI copilots without juggling checkout paths or branch names.

✨ Highlights

• ⚡ Instant setup: one command spins up or removes worktrees—zero path or branch wrangling.
• 🗂️ Hassle-free flow: wtm tracks everything so you never have to manage folder paths or branch names by hand.
• 🤖 AI-ready workflows: Agent Skills give assistants safe access without ceding control.
• 🛠️ Automation ready: structured output drops straight into your scripts and CI checks.

🚀 Quick Start

1. Install wtm (see Installation for available options).
2. Create a worktree: wtm add feature-auth.
3. Jump in and ship: cd .wtm/feature-auth or use the wcd helper below.

Example session

wtm add feature-login
wtm list
wtm show feature-login
wtm remove feature-login --force

📦 Installation

Homebrew (macOS/Linux)

brew install choplin/tap/wtm

Go install

go install github.com/choplin/wtm@latest

Build from source

git clone https://github.com/choplin/wtm.git
cd wtm
make build       # builds with version embedding
make install     # installs to $GOBIN
make install-git # installs as git-wtm for git subcommand usage
make test        # runs go test ./...

The make build target automatically discovers the version using git describe and falls back to dev when that metadata is unavailable.

Git subcommand

Install with make install-git to use wtm as a git subcommand:

git wtm add feature-auth
git wtm list
git wtm remove feature-auth

🧭 Usage Cheatsheet

Create a worktree

wtm add feature-auth
wtm add api -b feature/api-refactoring --base main
wtm add review-pr-456 -B origin/feature/complex-branch-name

By default, wtm add <name> creates a new branch and worktree that both use <name> so you can start working immediately without extra flags.

Options:

• -b, --branch <name>: Create a new branch with the provided name.
• -B, --checkout <name>: Use an existing branch.
• --base <branch>: Set the base branch for a new branch (defaults to current HEAD).
• -m, --message <text>: Attach a note to the worktree at creation time.

List worktrees

wtm list                # table (default)
wtm list --format plain # script-friendly
wtm list --format json  # machine-readable

Show worktree details

wtm show api
wtm show api --format json
wtm show api --field path
wtm show api -f branch

Available fields: name, branch, path, head, created, note.

Remove a worktree

wtm remove feature-auth
wtm remove feature-auth --force

Worktree notes

Attach freeform text notes to worktrees for context, summaries, or descriptions:

wtm notes add feature-auth -m "Implementing OAuth2 login flow"
wtm notes show feature-auth
wtm notes edit feature-auth   # opens $EDITOR
wtm notes remove feature-auth

Notes are stored inside Git's own management directories and are automatically cleaned up when the worktree is removed. They also appear in wtm show output.

Version information

wtm version

Shell completion

Generate completion scripts for your shell:

# Bash
wtm completion bash > /etc/bash_completion.d/wtm

# Zsh
wtm completion zsh > "${fpath[1]}/_wtm"

# Fish
wtm completion fish > ~/.config/fish/completions/wtm.fish

# PowerShell
wtm completion powershell > wtm.ps1

After setup, worktree names are auto-completed for show and remove commands.

Configuration

Edit the project configuration file (.wtm/config.toml):

wtm config edit

This opens the config file in your $EDITOR. If the file doesn't exist, it will be created.

🔌 Claude Code Plugin

wtm is also available as a Claude Code plugin, providing a worktree management skill that Claude can invoke automatically.

Install

1. Add the marketplace:

/plugin marketplace add choplin/wtm

2. Install and enable the plugin:

/plugin install wtm@wtm

Once enabled, Claude automatically recognizes worktree-related requests (e.g., "create a worktree", "list worktrees") and uses the wtm CLI to handle them.

Note: wtm must be available on your PATH for the plugin to work.

🪝 Hooks

Run commands and copy files automatically after creating a worktree. Hooks can be defined at two levels:

Global Hooks

Define hooks in ~/.config/wtm/config.toml (or $XDG_CONFIG_HOME/wtm/config.toml) to apply to all repositories: