git-worktree-manager (gw)

gw is a lean git worktree manager. Inspired by mr (myrepos), it uses cwd-based scope discovery — no global registry, no cross-repo flags — so commands do exactly what you expect relative to where you run them. Target resolution is strict and consistent: worktree name → branch name → path.

AI coding-assistant integration is built in: gw new creates a worktree and launches your AI tool of choice in it (use --no-term to skip). Future AI-assisted operations (e.g. --ai on merge / rebase) layer on top of the same worktree primitives.

Single static binary (~1.9MB), ~3ms startup. Supports macOS (ARM64/x86), Linux (ARM64/x86), and Windows (x86_64).

Successor to claude-worktree (Python), rewritten in Rust.

Backward compatible: The cw command is included as an alias. Existing cw workflows, .cwshare, and .cwconfig.json files work unchanged.

Install

cargo install git-worktree-manager

This installs both gw and cw binaries.

# Homebrew (macOS/Linux)
brew tap DaveDev42/tap
brew install git-worktree-manager

# cargo-binstall (pre-built binary, no compile)
cargo binstall git-worktree-manager

# Direct download
# https://github.com/DaveDev42/git-worktree-manager/releases/latest

After installing, run gw upgrade at any time to update to the latest version (self-replacing binary). Pass --yes to skip the prompt — required in non-TTY environments (CI, nested processes). Homebrew users should use brew upgrade git-worktree-manager instead.

Quick Start

# Create a worktree (and launch your AI coding assistant in it)
gw new fix-auth

# Just the worktree, no AI tool
gw new fix-auth --no-term

# Pass an initial prompt to the AI tool
gw new fix-auth --prompt "Fix the JWT token expiration bug in auth.rs"

# Or read the prompt from a file (recommended for multi-line / quoted content)
gw new fix-auth --prompt-file /tmp/task.md

# List all worktrees (rich human-readable output)
gw list

# Resume an AI session in an existing worktree
gw resume fix-auth

# Launch AI tool in the current worktree (or a named one)
gw spawn
gw spawn fix-auth

# Remove a worktree (interactive multi-select, or by name)
gw rm fix-auth
gw rm -i

# Run a command in every worktree in scope
gw run -- cargo test

# Run a command in one specific worktree
gw exec fix-auth -- git status

Commands

Scope and Target Resolution

Scope discovery

gw run, gw list, gw ls, and other scope-wide commands discover worktrees relative to the current working directory: it walks up first to find a .cwconfig.json-rooted scope, falling back to a downward walk from cwd if none is found. There is no global registry and no cross-repo flags.

Target resolution

When a command accepts a [target] argument, resolution is strict and ordered:

1. Exact worktree name
2. Branch name
3. Path

No ambiguity modes, no lookup-mode flags. The first match wins.

gw run and gw exec

gw run executes a command in every worktree in scope. gw exec runs in exactly one.

# Run tests in all worktrees, 4 in parallel
gw run -j 4 -- cargo test

# Only worktrees whose name matches a glob
gw run --only 'feat-*' -- npm install

# Skip the main worktree
gw run --no-main -- cargo clippy

# Keep going even if some worktrees fail
gw run --continue-on-error -- cargo build

# Run in one specific worktree
gw exec fix-auth -- git log --oneline -5

gw ls emits TSV columns (worktree_id, branch, status, age, repo_root, path) for scripting:

gw ls | awk -F'\t' '{print $2, $6}'   # branch + path

Terminal Launchers

The launcher used by gw new / gw spawn / gw resume is configured (not a per-invocation flag). Use --no-term on gw new to skip the AI tool launch entirely.

Set the default for a project in .cwconfig.json:

{ "launch_method": "tmux" }

…or globally in ~/.config/git-worktree-manager/config.json. Per-invocation override is via the CW_LAUNCH_METHOD env var:

CW_LAUNCH_METHOD=iterm-tab gw new fix-auth

Claude Code Integration

Install the gw plugin into your Claude Code setup:

gw setup-claude    # One-time: installs the gw plugin to ~/.claude/plugins/gw/

The plugin bundles two skills:

• delegate — invoked via /gw <task description>. Spawns a new worktree and a Claude Code session inside it with the given task as the initial prompt. One-shot, fire-and-forget.
• manage — auto-applies when you (or Claude) run worktree management commands. Encodes a worktree-health rulebook and a catalog of recommended Claude Code hooks. When relevant, Claude will suggest installing a hook into your project's .claude/settings.json and edit it on your consent — gw itself never modifies any settings file.

Shell Integration

# Interactive setup (recommended)
gw shell-setup

# bash/zsh — add to your shell rc file
source <(gw _shell-function bash)

# fish
gw _shell-function fish | source

This enables:

• gw-cd <target> — navigate to a worktree directory (interactive selector if no args)
• Tab completion — worktree names and branch names from the current scope, plus options

Generate shell completions separately with gw --generate-completion <bash|zsh|fish|powershell|elvish>.

Configuration

Config is resolved in layers (later layers override earlier ones): built-in defaults → ~/.config/git-worktree-manager/config.json → repo-local .cwconfig.json. There are no gw config subcommands — edit the JSON files directly.

Also reads legacy ~/.config/claude-worktree/config.json from the Python predecessor.

Example .cwconfig.json:

{
  "default_base": "main",
  "ai_tool": "claude",
  "launch_method": "tmux",
  "hooks": {
    "post_new": "npm install",
    "pre_rm": "cargo test --quiet"
  }
}

Hooks

Two lifecycle hooks are available, configured in .cwconfig.json (or the global config):

Hooks run as sh -c <cmd> with the worktree directory as the working directory.

• pre_rm non-zero exit aborts the remove (the worktree stays). This is independent of --force — --force bypasses busy detection, not user hooks.
• post_new non-zero exit surfaces as a non-zero gw new exit code, but the worktree itself remains on disk because the hook runs after git worktree add. The AI tool launch is skipped.

There are no gw hook CRUD subcommands — set hooks in the config file directly.

Doctor

gw doctor runs 5 lean health checks: git version, worktree accessibility, uncommitted changes, busy worktrees, and Claude Code integration. Pass --session-start for hook-friendly non-interactive mode (single-line summary, always exits 0).

gw rm Exit Codes

Scripts should handle != 0 or specifically check for 2.

License

BSD-3-Clause