git-worktree-manager (gw)

CLI tool integrating git worktree with AI coding assistants. Single static binary (~1.9MB), instant startup (~3ms).

Supports macOS (ARM64/x86), Linux (ARM64/x86), and Windows (x86_64).

Successor to claude-worktree (Python).

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
gw new fix-auth

# Create with a specific terminal launcher
gw new fix-auth --term tmux

# Create and pass an initial prompt to the AI tool (short one-liner)
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

# Or pipe it from another command
generate-spec | gw new fix-auth --prompt-stdin

Note: avoid combining --prompt-stdin with --term — the spawned terminal may inherit a closed stdin and behave unpredictably.

# List all worktrees
gw list

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

# Create a GitHub PR
gw pr

# Merge back to base branch and clean up
gw merge

Commands

Terminal Launchers

Control how AI tools are launched with --term (or configure a default via gw config set launch.method):

gw new fix-auth --term tmux         # New tmux session
gw new fix-auth --term iterm-tab    # New iTerm tab
gw new fix-auth --term zellij       # New Zellij session
gw new fix-auth --term wezterm-tab  # New WezTerm tab
gw resume fix-auth --bg             # Background launch

Each launcher also has a short alias (e.g., t for tmux, i-t for iterm-tab).

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 (gw list/delete/clean/sync/merge/pr/resume). Encodes a worktree-health rulebook (stale cwd, wrong-base branching, sibling drift, missing test/lint conventions) 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.

Behavior changes in this release

• gw delete no longer prompts. Refusal messages now include a tiered explanation (Hard tier: active Claude session in the worktree, lockfile holder; Soft tier: process cwd scan). Pass --force once to override either tier — there is no interactive y/N path. Automation that piped y should switch to --force.
• gw delete detects active Claude Code sessions. A worktree with a Claude Code session that wrote a JSONL event in the last 10 minutes refuses delete, even if the session was started by another gw new call. This directly prevents the "second session deletes the worktree the first session is working in" failure mode. Override with --force.

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 <branch> - Navigate to a worktree directory (interactive selector if no args)
• Tab completion - Branch names, config keys, and options

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

Configuration

Config file: ~/.config/git-worktree-manager/config.json (also reads legacy ~/.config/claude-worktree/config.json)

gw config show                     # Show current config
gw config list                     # List all keys with descriptions
gw config set <key> <value>        # Set a value
gw config get <key>                # Get a value
gw config reset                    # Reset to defaults

AI Tool Presets

gw config use-preset claude              # Default
gw config use-preset claude-yolo         # Skip permission prompts
gw config use-preset claude-remote       # Remote control mode
gw config use-preset claude-yolo-remote  # Remote + skip permissions
gw config use-preset codex               # OpenAI Codex
gw config use-preset codex-yolo          # Codex without sandbox
gw config use-preset no-op               # No AI tool

Environment Variables

Hooks

Run custom commands at lifecycle events. Pre-hooks abort the operation on failure.

gw hook add worktree.post_create "npm install"
gw hook add pr.pre "cargo test" --description "Run tests before PR"
gw hook list
gw hook disable worktree.post_create <hook-id>

Available events: worktree.pre_create, worktree.post_create, worktree.pre_delete, worktree.post_delete, merge.pre, merge.post, pr.pre, pr.post, resume.pre, resume.post, sync.pre, sync.post

Hook context is passed via CW_* environment variables.

Notes

Behavior change in gw delete

Since the multi-target gw delete change (#100), single-target failures now exit with code 2 instead of 1. This aligns with the new batch contract:

• 0 — full success, --dry-run, or interactive (-i) with no eligible worktrees / nothing selected
• 1 — user cancelled
• 2 — any target failed or was skipped (not found, busy, remove error)

Scripts treating exit code 1 as "delete failed" should switch to != 0 or specifically handle 2. See gw delete --help for the full contract.

License

BSD-3-Clause