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). 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
gw new fix-auth --prompt "Fix the JWT token expiration bug in auth.rs"

# 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

Delegate coding tasks to isolated worktrees directly from Claude Code:

gw setup-claude    # One-time setup: installs the /gw skill

Once installed, use the /gw slash command or natural language in Claude Code to delegate tasks. Each task runs in its own worktree with a separate Claude Code instance.

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.

License

BSD-3-Clause