wt

wt - Git Worktree Manager

     

A fast, simple Git worktree helper written in Go. Inspired by haacked/dotfiles/tree-me.

!wt quickstart

Features

• Configurable worktree strategies: global, sibling-repo, parent-branches, and more
• Simple commands for common worktree operations
• Interactive selection menus with fuzzy matching for checkout, remove, pr, and mr commands
• GitHub PR support via wt pr command (uses gh CLI) — checks out the PR's actual branch name
• GitLab MR support via wt mr command (uses glab CLI) — checks out the MR's actual branch name
• Pre/post command hooks — run custom scripts on create/checkout/remove (e.g. launch AI assistants, share build caches, assign dev server ports, copy .env, init submodules)
• Stale worktree detection — find worktrees with deleted remote branches or inactive commits (wt cleanup --stale)
• Color-coded status output — green (clean), red (dirty), yellow (ahead/behind), bold cyan (current); respects NO_COLOR=1 and auto-strips colors when piped
• CI/CD status integration — wt status --ci shows pipeline status (✓/✗/●) per branch via gh or glab CLI
• Per-repo .wt.toml config — override global settings (strategy, hooks, etc.) on a per-repository basis
• Shell integration with auto-cd functionality
• Tab completion for Bash, Zsh, and Fish

Quick Start

brew install timvw/tap/wt   # or: go install github.com/timvw/wt@latest
wt init                      # configure shell integration

See docs/installation.md for all platforms (Scoop, WinGet, Linux packages, from source).

Usage

Checkout & Create

# Checkout existing branch in new worktree
wt co feature-branch
wt co                             # interactive: fuzzy-search from available branches

# Create new branch in worktree (defaults to main/master as base)
wt create my-feature
wt create my-feature develop      # specify base branch

PRs & MRs

!wt pr

# Checkout GitHub PR (requires gh CLI)
wt pr 123                                          # looks up branch for PR #123
wt pr https://github.com/org/repo/pull/123         # GitHub PR URL
wt pr                                              # interactive: fuzzy-search from open PRs

# Checkout GitLab MR (requires glab CLI)
wt mr 123                                          # looks up branch for MR !123
wt mr https://gitlab.com/org/repo/-/merge_requests/123  # GitLab MR URL
wt mr                                              # interactive: fuzzy-search from open MRs

List & Remove

!wt create

wt ls                             # list all worktrees
wt rm old-branch                  # remove a worktree
wt rm                             # interactive: fuzzy-search worktree to remove

Maintenance & Misc

wt migrate                        # migrate worktrees to configured paths
wt migrate --force                # force when target path exists
wt cleanup --stale                # detect stale worktrees (deleted remotes, inactive commits)
wt cleanup --stale --stale-days 7 # custom inactivity threshold (default: 30 days)
wt prune                          # clean up stale worktree admin files
wt version                        # show version
wt examples                       # show practical examples
wt --help                         # show help

Info & Config

!wt info

wt info                           # show active strategy, pattern, variables
wt config show                    # show effective config with sources (global + repo .wt.toml)
wt config init                    # create a default config file
wt config path                    # print the config file path
# Place a .wt.toml in a repo root to override global config for that repo

On case-insensitive filesystems such as the default macOS APFS setup, mixed-case branch prefixes can produce confusing worktree paths. For example, Feature/foo and

feature/bar both need a first-level directory that macOS treats as the same name. Set separator = "-" to flatten branch paths (Feature/foo -> Feature-foo) and avoid that class of collision. See Configuration.

Status Dashboard

!wt status

wt status                         # color-coded overview of all worktrees
wt status --ci                    # include CI/CD pipeline status (requires gh or glab)

Shows dirty/clean state, ahead/behind counts, and highlights the current worktree. With --ci, each branch shows ✓ (pass), ✗ (fail), or ● (pending) for its latest CI pipeline. Colors are automatically stripped when piping; set NO_COLOR=1 to disable.

Interactive Selection

!wt interactive

When you run wt co, wt rm, wt pr, or wt mr without arguments, you'll get an interactive selection menu. Typing filters the results with fuzzy matching, so you can quickly find the branch or worktree you're looking for.

JSON Output (--format json)

Most commands support machine-readable JSON output:

wt --format json version
wt --format json info
wt --format json config show
wt --format json list
wt --format json examples

In json mode, shell integration does not auto-navigate. For commands that normally prompt interactively, pass explicit arguments when using --format json.

Use with Claude Code

Install the Claude Code plugin to teach Claude how to work with wt-managed worktrees:

claude plugin marketplace add timvw/wt
claude plugin install wt@wt --scope local

Once installed, Claude understands wt commands, worktree strategies, and hooks — so you can ask it to create worktrees, set up hooks for copying .env files or running npm install / uv sync, and follow worktree-based workflows automatically.

See docs/examples.md for hooks that launch Claude Code in tmux per worktree.

Documentation

| Topic | Description | | --- | --- | | Configuration | Config file, strategies, patterns, separator, hooks, per-repo .wt.toml | | Examples | Claude Code + tmux, multi-repo workflows, environment variables | | Installation | All platforms, shell integration, building from source | | Development | Building, testing, running from source | | Claude Code Plugin | Plugin that teaches Claude Code how to work with wt |

How It Works

The tool wraps Git's native worktree commands with a convenient interface and organized directory structure:

1. Organized Structure: All worktrees for a repo are kept together 2. Smart Defaults: Automatically detects repo name and default branch 3. Prevents Duplicates: Checks if a worktree already exists before creating 4. Auto-CD: With shell integration, automatically changes to the worktree directory 5. Tab Completion: Makes it easy to work with existing branches

License

MIT

Credits

Based on tree-me by Phil Haack.