К основному содержанию
скилл CX Codex

git-worktree — скилл для Claude Code: что делает и как установить

Управляет параллельными рабочими деревьями git worktree с созданием окон tmux и вкладок iTerm2. Помогает работать над ветками без stash.

MIT 111 установок ★ 17 обновлён 2026-10-14

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add julianobarbosa/claude-code-skills --skill git-worktree -a claude-code
Открыть на GitHub

Что делает git-worktree

Скилл настраивает изолированные рабочие окружения через подкаталог .worktrees внутри проекта. Набор функций shell во главе с wt автоматизирует добавление веток: скрипт проверяет репозиторий, создаёт отдельную директорию и сразу переносит туда терминальную сессию.

В связке с tmux инструмент создаёт отдельное окно с именем ветки или запускает персональную сессию через wt-session. Если используется macOS и iTerm2, скрипты на AppleScript открывают под каждую ветку новую вкладку или окно терминала с готовым переходом по пути cd.

Функция очистки wt-rm удаляет рабочее дерево через флаг --force и закрывает окно tmux, поэтому незакоммиченные локальные изменения в удаляемом воркдереве сотрутся без предупреждения.

Какие задачи решает

  • переключаться между задачами без git stash и потери контекста
  • запускать параллельные сессии Claude Code в одном репозитории
  • создавать отдельные именованные окна tmux под каждое дерево
  • открывать вкладки iTerm2 с автоматическим переходом в папку ветки
  • удалять завершённые воркдеревья вместе с терминальными окнами

Примеры запросов агенту

  • Создай воркдерево для ветки feature-auth и переключись на него
  • Покажи все активные git worktree в текущем проекте
  • Удали рабочее дерево для ветки bugfix-login и закрой его окно tmux

Как установить git-worktree

1Через Skills CLI (Vercel)

npx skills add julianobarbosa/claude-code-skills --skill git-worktree -a claude-code

2Вручную: положить файлы

~/.claude/skills/git-worktree/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/git-worktree/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о git-worktree

Как установить git-worktree в Claude Code?

Выполните в терминале команду npx skills add julianobarbosa/claude-code-skills --skill git-worktree -a claude-code либо сохраните файл по пути ~/.claude/skills/git-worktree/SKILL.md.

Где хранятся созданные рабочие деревья?

Скрипты размещают все каталоги внутри корневой папки текущего репозитория по пути .worktrees/<имя_ветки>.

Что произойдёт, если запустить wt вне tmux?

Если переменная $TMUX не задана, функция просто сменит текущую директорию на созданный воркдерево с помощью cd.

Исходный текст

SKILL.md · MIT
---
name: git-worktree
description: Git worktree management with tmux and iTerm2 integration. Use when creating isolated dev environments, managing parallel feature branches, switching contexts without stashing, or running multiple Claude instances. Covers worktree creation, tmux window management, iTerm2 tabs, and cleanup workflows.
---

# Git Worktree Skill

Manage parallel development environments using git worktrees with seamless terminal integration.

## Overview

Git worktrees enable multiple working directories from a single repository:
- Isolated feature development without branch switching
- Run multiple Claude Code instances in parallel
- Context switching without stashing uncommitted changes
- Clean separation of experimental work

## Quick Commands

### wt - Worktree Manager

The `wt` command creates worktrees with automatic terminal integration:

```bash
# Create worktree with tmux window
wt add-new-feature

# This will:
# 1. Create git worktree named 'add-new-feature'
# 2. Create new tmux window in current session
# 3. Rename window to 'add-new-feature'
# 4. Change directory to the worktree
```

## tmux Integration

### Workflow: Create Worktree + tmux Window

```bash
# Function for ~/.zshrc or ~/.bashrc
wt() {
    local name="$1"
    local base_branch="${2:-main}"
    local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
    local worktree_path="$repo_root/.worktrees/$name"

    # Validate we're in a git repo
    if [[ -z "$repo_root" ]]; then
        echo "Error: Not in a git repository"
        return 1
    fi

    # Create worktree directory
    mkdir -p "$repo_root/.worktrees"

    # Create worktree with new branch
    if git worktree add -b "$name" "$worktree_path" "$base_branch" 2>/dev/null; then
        echo "Created worktree: $worktree_path"
    elif git worktree add "$worktree_path" "$name" 2>/dev/null; then
        echo "Attached to existing branch: $name"
    else
        echo "Error: Failed to create worktree"
        return 1
    fi

    # tmux integration
    if [[ -n "$TMUX" ]]; then
        # Create new window with worktree name
        tmux new-window -n "$name" -c "$worktree_path"
        echo "Created tmux window: $name"
    else
        # Not in tmux, just cd
        cd "$worktree_path"
        echo "Changed to: $worktree_path"
    fi
}

# Remove worktree and tmux window
wt-rm() {
    local name="$1"
    local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
    local worktree_path="$repo_root/.worktrees/$name"

    # Remove git worktree
    git worktree remove "$worktree_path" --force 2>/dev/null

    # Close tmux window if exists
    if [[ -n "$TMUX" ]]; then
        tmux kill-window -t "$name" 2>/dev/null
    fi

    # Optionally delete branch
    git branch -d "$name" 2>/dev/null

    echo "Removed worktree: $name"
}

# List all worktrees
wt-ls() {
    git worktree list
}
```

### tmux Session Management

```bash
# Create dedicated tmux session per project
wt-session() {
    local name="$1"
    local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
    local worktree_path="$repo_root/.worktrees/$name"

    # Create worktree first
    wt "$name"

    # Create new tmux session (or attach if exists)
    if tmux has-session -t "$name" 2>/dev/null; then
        tmux attach-session -t "$name"
    else
        tmux new-session -d -s "$name" -c "$worktree_path"
        tmux attach-session -t "$name"
    fi
}
```

## iTerm2 Integration

### AppleScript for iTerm2 Tabs

```bash
# Function for ~/.zshrc
wt-iterm() {
    local name="$1"
    local base_branch="${2:-main}"
    local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
    local worktree_path="$repo_root/.worktrees/$name"

    # Create worktree
    mkdir -p "$repo_root/.worktrees"
    git worktree add -b "$name" "$worktree_path" "$base_branch" 2>/dev/null || \
    git worktree add "$worktree_path" "$name" 2>/dev/null

    # Open in new iTerm2 tab
    osascript <<EOF
tell application "iTerm2"
    tell current window
        create tab with default profile
        tell current session
            write text "cd '$worktree_path' && clear"
        end tell
    end tell
end tell
EOF

    echo "Created worktree with iTerm2 tab: $name"
}

# Open worktree in new iTerm2 window
wt-iterm-window() {
    local name="$1"
    local base_branch="${2:-main}"
    local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
    local worktree_path="$repo_root/.worktrees/$name"

    # Create worktree
    mkdir -p "$repo_root/.worktrees"
    git worktree add -b "$name" "$worktree_path" "$base_branch" 2>/dev/null || \
    git worktree add "$worktree_path" "$name" 2>/dev/null

    # Open in new iTerm2 window
    osascript <<EOF
tell application "iTerm2"
    create window with default profile
    tell current session of current window
        write text "cd '$worktree_path' && clear"
    end tell
end tell
EOF

    echo "Created worktree with iTerm2 window: $name"
}
```

### iTerm2 Profile Integration

Create a dedicated iTerm2 profile for worktrees:

```json
{
  "Name": "Worktree",
  "Badge Text": "WT: \\(session.name)",
  "Working Directory": "$HOME/.worktrees",
  "Custom Directory": "Yes"
}
```

## Configuration

### Environment Variables

```bash
# Add to ~/.zshrc or ~/.bashrc

# Preferred terminal for worktree operations (auto-detected if not set)
export WORKTREE_TERMINAL="tmux"  # or "iterm2" or "auto"

# Auto-install dependencies after creating worktree
export WORKTREE_AUTO_INSTALL=true
```

### Worktree Location

Worktrees are stored **inside the project directory**:

```
~/Repos/github/my-project/
├── .worktrees/
│   ├── feature-auth/      # worktree for feature-auth branch
│   ├── bugfix-login/      # worktree for bugfix-login branch
│   └── add-new-skill/     # worktree for add-new-skill branch
├── src/
├── package.json
└── ...
```

### Shell Configuration

Functions are defined in `~/.zsh/functions.zsh` (already loaded by your zshrc):

```zsh
# Functions location: ~/.zsh/functions.zsh

# Aliases
alias wt='wt'
alias wtl='wt-ls'
alias wtr='wt-rm'
alias wts='wt-session'

# Completion for wt commands
_wt_completion() {
    local branches=$(git branch --format='%(refname:short)' 2>/dev/null)
    local worktrees=$(git worktree list --porcelain 2>/dev/null | grep '^worktree' | cut -d' ' -f2 | xargs -I{} basename {})
    _alternative \
        "branches:branch:($branches)" \
        "worktrees:worktree:($worktrees)"
}
compdef _wt_completion wt wt-rm
```

## Git Worktree Commands Reference

### Creating Worktrees

```bash
# Create worktree with new branch from current HEAD
git worktree add ../feature-x -b feature-x

# Create worktree from specific branch
git worktree add ../hotfix hotfix-branch

# Create worktree from remote branch
git worktree add ../upstream upstream/main

# Create worktree at specific commit
git worktree add ../review abc123
```

### Managing Worktrees

```bash
# List all worktrees
git worktree list

# Show worktree details (porcelain format)
git worktree list --porcelain

# Lock worktree (prevent pruning)
git worktree lock ../feature-x --reason "WIP"

# Unlock worktree
git worktree unlock ../feature-x

# Remove worktree
git worktree remove ../feature-x

# Force remove (discards changes)
git worktree remove ../feature-x --force

# Prune stale worktrees
git worktree prune
```

### Advanced Operations

```bash
# Move worktree to new location
git worktree move ../old-path ../new-path

# Repair worktree after manual move
git worktree repair ../moved-worktree
```

## Parallel Claude Development

### Running Multiple Instances

```bash
# Create worktrees for parallel development
wt feature-auth
wt feature-api
wt bugfix-login

# Each worktree gets its own:
# - tmux window / iTerm2 tab
# - Git index and working directory
# - Port allocation (if configured)
# - Claude Code instance
```

### Port Management

```bash
# Configure port pools per worktree
export WORKTREE_PORT_BASE=8100
export WORKTREE_PORTS_PER_TREE=2

# Calculate ports for worktree
get_worktree_ports() {
    local index=$(git worktree list | grep -n "$PWD" | cut -d: -f1)
    local base=$((WORKTREE_PORT_BASE + (index - 1) * WORKTREE_PORTS_PER_TREE))
    echo "Dev server: $base, API: $((base + 1))"
}
```

## Cleanup Workflows

### Merge and Cleanup

```bash
# After PR merge, clean up worktree
wt-cleanup() {
    local name="$1"
    local repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
    local worktree_path="$repo_root/.worktrees/$name"

    # Switch to main worktree
    cd "$repo_root"

    # Update main
    git fetch origin
    git pull origin main

    # Remove worktree
    git worktree remove "$worktree_path" --force

    # Delete branch if merged
    if git branch --merged | grep -q "$name"; then
        git branch -d "$name"
        echo "Branch $name was merged and deleted"
    else
        echo "Branch $name not yet merged, kept locally"
    fi

    # Close tmux window
    [[ -n "$TMUX" ]] && tmux kill-window -t "$name" 2>/dev/null
}
```

### Bulk Cleanup

```bash
# Remove all worktrees with merged branches
wt-cleanup-merged() {
    local main_dir=$(git worktree list | head -1 | awk '{print $1}')

    git worktree list | tail -n +2 | while read -r line; do
        local wt_path=$(echo "$line" | awk '{print $1}')
        local wt_branch=$(echo "$line" | awk '{print $3}' | tr -d '[]')

        if git branch --merged main | grep -q "$wt_branch"; then
            echo "Removing merged worktree: $wt_branch"
            git worktree remove "$wt_path" --force
            git branch -d "$wt_branch"
        fi
    done
}
```

## Troubleshooting

### Common Issues

**Worktree already exists:**
```bash
# List existing worktrees
git worktree list

# Remove stale entry
git worktree prune
```

**Branch already checked out:**
```bash
# Error: 'branch' is already checked out at '/path'
# Solution: Use a different branch name or remove existing worktree
git worktree remove /path/to/existing
```

**tmux window naming conflicts:**
```bash
# Rename existing window first
tmux rename-window -t old-name new-name

# Or kill conflicting window
tmux kill-window -t conflicting-name
```

**iTerm2 AppleScript errors:**
```bash
# Ensure iTerm2 is running
open -a iTerm

# Grant automation permissions
# System Preferences > Security & Privacy > Privacy > Automation
```

## References

- [references/tmux-config.md](references/tmux-config.md) - tmux configuration for worktrees
- [references/iterm2-config.md](references/iterm2-config.md) - iTerm2 profile setup
- Shell functions: `~/.zsh/functions.zsh`

## External Links

- Git Worktree Documentation: https://git-scm.com/docs/git-worktree
- tmux Manual: https://man.openbsd.org/tmux
- iTerm2 Documentation: https://iterm2.com/documentation.html

---

## Gotchas

- **Worktree paths inside the main repo's working tree confuse the outer `git status`** — files in the inner worktree show as untracked in the parent.
- **A branch checked out in any worktree refuses `git branch -d`** — must remove the worktree first.
- **Worktrees share `.git/config`** — per-worktree config needs explicit `git config --worktree`.
- **`git worktree prune` removes orphaned records but does NOT delete the directory** — clean up the dir manually after pruning.
- **Locking a worktree doesn't prevent fs operations** — `git worktree lock` only blocks `git worktree remove`; `rm -rf` still works.
- **macOS case-insensitive fs + worktrees**: two worktrees with case-only-different paths cause unpredictable git behavior.

© julianobarbosa · MIT · julianobarbosa/claude-code-skills

Похожие скиллы

Все скиллы по теме «Git и GitHub» →
git-worktree-isolation sentimony Скилл git-worktree-isolation оценивает риски правок и подбирает безопасное рабочее пространство перед началом задач. Помогает избежать затирания чужого кода при параллельной работе агентов. CX Codex +1 2 300установок git-worktree-manager Alireza Rezvani Скилл git-worktree-manager для Claude Code создаёт изолированные Git worktrees для параллельной работы над ветками. Он назначает портам отдельные значения, копирует файлы окружения и помогает безопасно убрать устаревшие worktrees. CX Codex +1 581установок git-merge-expert-worktree ulpi-io Скилл git-merge-expert-worktree для Claude Code и ещё пяти агентных сред: выполняет слияния и решение конфликтов в отдельном git worktree. CX Codex +1 159установок git-worktree-runner dyoshikawa Скилл git-worktree-runner учит агента управлять git worktree через CLI-обёртку gtr: создавать, открывать в редакторе, запускать команды и удалять. CX Codex +1 ★ 1 636звёзд репо remove-worktree FlorianBruniaux Команда remove-worktree для Claude Code и Codex удаляет worktree по имени ветки: каталог, запись в git и локальную ветку. Убирает рабочие копии после влитых PR. CX Codex +1 ★ 6 529звёзд репо worktree-status FlorianBruniaux Команда worktree-status показывает статус всех активных git-ворктри: ветку, путь, хэш коммита и число изменённых файлов. CX Codex +1 ★ 6 529звёзд репо

Из того же набора37

Весь набор →
repomix Скилл repomix упаковывает репозиторий в один файл, который читает LLM: отбор файлов, сжатие до сигнатур, подсчёт токенов. Пригодится перед ревью и когда код надо втиснуть в контекст. CX Codex +1 115установок managing-infra Скилл managing-infra помогает выбрать между Helm и Kustomize, настроить модули Terraform и применить базовые стандарты безопасности в Kubernetes. CX Codex +1 115установок iterm2 Настраивает iTerm2 и tmux, управляет панелями и сессиями и разбирает неполадки. Помогает работать с терминалом на macOS. CX Codex +1 115установок context7 Скилл ищет документацию и примеры кода для конкретной версии библиотеки через Context7. Пригодится перед написанием кода по API, в котором вы не уверены. CX Codex +1 114установок writing-typescript Скилл writing-typescript задаёт идиоматичный стиль TypeScript для сервисов Node.js, React-приложений и обсуждения TS-паттернов. Поддерживает строгую типизацию и современный toolchain. CX Codex +1 111установок az-aks-agent Скилл az-aks-agent для Claude Code разбирает состояние и настройки кластера Azure Kubernetes Service по запросам на обычном языке. Ищет проблемы с подами, сетью, хранилищем и RBAC. CX Codex +1 110установок writing-go Скилл writing-go задаёт агенту правила написания Go: стандартная библиотека вместо зависимостей, конкретные типы, ошибки с контекстом, табличные тесты. CX Codex +1 110установок macos-cleaner Скилл macos-cleaner анализирует, чем занято место на Mac, и предлагает варианты очистки. Он пригодится, когда нужно найти крупные файлы и оценить последствия удаления. CX Codex +1 109установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой