manage-worktrees

What this skill does

# 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:

```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`

```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`)