manage-worktrees

WT - Git Worktree Manager

WT manages git worktrees with dedicated iTerm2 windows on macOS. Each worktree gets a window with Claude Code on top and a shell on bottom.

MCP Tools (Preferred)

When the wt MCP server is installed, use these tools directly:

wt_list

List worktrees for a repository with status information.

• repo_path (required): Absolute path to the git repository

wt_create

Create a new worktree + branch + iTerm2 window.

• repo_path (required): Absolute path to the git repository
• branch (required): Branch name for the worktree
• base (optional): Base branch to create from (default: main)
• no_claude (optional): Don't auto-launch Claude in top pane

wt_open

Open or focus an iTerm2 window for an existing worktree.

• repo_path (required): Absolute path to the git repository
• branch (required): Branch name of the worktree to open
• no_claude (optional): Don't auto-launch Claude in top pane

wt_delete

Close iTerm2 window and remove worktree.

• repo_path (required): Absolute path to the git repository
• branch (required): Branch name of the worktree to delete
• force (optional): Force removal, skip safety checks

wt_sync

Sync worktree with base branch (merge or rebase base into feature).

• repo_path (required): Absolute path to the git repository
• branch (required): Branch name of the worktree to sync
• strategy (optional): merge (default) or rebase

wt_merge

Merge worktree branch into base branch or push for PR.

• repo_path (required): Absolute path to the git repository
• branch (required): Branch name of the worktree to merge
• strategy (optional): merge (default) or rebase (rebase-then-fast-forward)
• pr (optional): Push branch for PR instead of local merge

CLI Fallback

If MCP tools are unavailable, use the wt CLI via Bash:

# List worktrees
wt list

# Create worktree (also: wt new, wt create)
wt create feature/my-branch
wt create feature/my-branch --base develop
wt create feature/my-branch --no-claude

# Open/focus existing worktree
wt open feature/my-branch
wt feature/my-branch          # shorthand

# Delete worktree
wt delete feature/my-branch
wt delete feature/my-branch --force
wt delete --all

# Sync with base branch
wt sync feature/my-branch
wt sync feature/my-branch --rebase
wt sync --all

# Merge into base
wt merge feature/my-branch
wt merge feature/my-branch --rebase
wt merge feature/my-branch --pr
wt merge feature/my-branch --pr --draft

Configuration

Config file: ~/.config/wt/config.yaml

base_branch: main       # Default base branch
no_claude: false         # Skip Claude in iTerm windows
rebase: false            # Use rebase instead of merge by default
state_dir: ~/.config/wt  # Where state.json is stored

Environment variables override config: WT_BASE_BRANCH, WT_NO_CLAUDE, WT_REBASE.

Workflow Examples

New Feature

1. wt_create with branch feature/my-feature - creates worktree + iTerm window
2. Work in the new worktree (separate Claude Code session)
3. wt_sync to pull in latest changes from main
4. wt_merge with pr=true to push and create PR, or without pr for local merge

Review a Branch

1. wt_create with the existing branch name - detects it exists and checks it out
2. Review code in the dedicated iTerm window
3. wt_delete when done reviewing

Cleanup

1. wt_list to see all worktrees and their status
2. wt_delete stale worktrees (check for dirty/unpushed first)

Important Notes

• The repo_path parameter must be an absolute path to the git repository
• Worktrees are created in <repo_path>.worktrees/<dirname>/
• The dirname is the last segment of the branch name (e.g., feature/login -> login)
• Safety checks prevent deleting worktrees with uncommitted changes or unpushed commits unless force=true
• MCP server installation: wt mcp install (writes to ~/.claude.json)