Development ★ 132

worktree-manager

Claude Code ajanlarıyla tüm projelerinizde git worktree'leri oluşturun, yönetin ve temizleyin. Kullanıcı "create worktree", "spin up worktrees", "new worktree for X", "worktree status", "cleanup worktrees", "sync worktrees" dediğinde veya paralel geliştirme branşları istediğinde bu skill'i kullanın. Worktree branch'inden PR oluşturulurken de devreye girer (registry'yi PR numarasıyla günceller). Worktree oluşturma ve dependency yönetimini otomatikleştirir.

cd ~/.claude/skills
git clone https://github.com/Wirasm/worktree-manager-skill.git worktree-manager-skill

Global Worktree Manager

Tüm projelerde git worktrees kullanarak paralel geliştirmeyi yönetin ve Claude Code ajanlarıyla çalışın. Her worktree, farklı bir dalda yer alan ve merkezi olarak ~/tmp/worktrees/ konumunda depolanan izole bir repo kopyasıdır.

ÖNEMLİ: Sen (Claude) tüm işlemleri standart araçlar (jq, git, bash) kullanarak manuel olarak gerçekleştirebilirsin. Scriptler yardımcıdır, gereklilik değildir. Eğer bir script başarısız olursa, bu dokümanda açıklanan manuel işlemlere geri dön.

Bu Beceri Ne Zaman Aktivize Olur

Tetikleme ifadeleri:

  • "X, Y, Z için worktrees oluştur"
  • "A, B, C özellikleri için 3 worktree oluştur"
  • "feature/auth için yeni worktree"
  • "worktreelerim durumu nedir?"
  • "tüm worktrees göster" / "bu projenin worktreeslerini göster"
  • "birleştirilen worktrees temizle"
  • "auth worktreesini temizle"
  • "X worktreesinde ajan başlat"
  • "worktrees senkronize et" / "worktree registry senkronize et"
  • "PR oluştur" (worktree içindeyken - registry'yi PR numarasıyla güncelle)

Dosya Konumları

Dosya Amaç
~/.claude/worktree-registry.json Global registry - tüm projelerdeki tüm worktrees'i izler
~/.claude/skills/worktree-manager/config.json Beceri konfigürasyonu - terminal, shell, port aralığı ayarları
~/.claude/skills/worktree-manager/scripts/ Yardımcı scriptler - isteğe bağlı, her şeyi manuel yapabilirsin
~/tmp/worktrees/ Worktree depolaması - tüm worktrees burada yaşar
.claude/worktree.json (proje başına) Proje konfigürasyonu - isteğe bağlı özel ayarlar

Temel Konseptler

Merkezi Worktree Depolaması

Tüm worktrees ~/tmp/worktrees/<project-name>/<branch-slug>/ altında yaşar

~/tmp/worktrees/
├── obsidian-ai-agent/
│   ├── feature-auth/           # dal: feature/auth
│   ├── feature-payments/       # dal: feature/payments
│   └── fix-login-bug/          # dal: fix/login-bug
└── another-project/
    └── feature-dark-mode/

Branch Slug Konvansiyonu

Dal adları dosya sistemi güvenliği için / yerine - konularak slug haline getirilir:

  • feature/authfeature-auth
  • fix/login-bugfix-login-bug
  • feat/user-profilefeat-user-profile

Manuel slug haline getir: echo "feature/auth" | tr '/' '-'feature-auth

Port Tahsis Kuralları

  • Global pool: 8100-8199 (toplam 100 port)
  • Worktree başına: 2 port tahsis edilir (API + frontend desenleri için)
  • Global olarak benzersiz: Portlar projelerde çatışmaları önlemek için global olarak izlenir
  • Kullanmadan önce kontrol et: Portu sistem tarafından kullanılmadığından emin ol: lsof -i :<port>

Global Registry

Konum

~/.claude/worktree-registry.json

Şema

{
  "worktrees": [
    {
      "id": "unique-uuid",
      "project": "obsidian-ai-agent",
      "repoPath": "/Users/rasmus/Projects/obsidian-ai-agent",
      "branch": "feature/auth",
      "branchSlug": "feature-auth",
      "worktreePath": "/Users/rasmus/tmp/worktrees/obsidian-ai-agent/feature-auth",
      "ports": [8100, 8101],
      "createdAt": "2025-12-04T10:00:00Z",
      "validatedAt": "2025-12-04T10:02:00Z",
      "agentLaunchedAt": "2025-12-04T10:03:00Z",
      "task": "OAuth girişini uygula",
      "prNumber": null,
      "status": "active"
    }
  ],
  "portPool": {
    "start": 8100,
    "end": 8199,
    "allocated": [8100, 8101]
  }
}

Alan Açıklamaları

Worktree girdisi alanları:

Alan Tür Açıklama
id string Benzersiz tanımlayıcı (UUID)
project string Proje adı (git remote veya dizinden)
repoPath string Orijinal repository'ye mutlak yol
branch string Tam dal adı (ör. feature/auth)
branchSlug string Dosya sistemi güvenli adı (ör. feature-auth)
worktreePath string Worktree'ye mutlak yol
ports number[] Tahsis edilen port numaraları (genellikle 2)
createdAt string ISO 8601 zaman damgası
validatedAt string|null Doğrulama ne zaman başarılı oldu
agentLaunchedAt string|null Ajan ne zaman başlatıldı
task string|null Ajan için görev açıklaması
prNumber number|null İlişkili PR numarası varsa
status string active, orphaned, veya merged

Port pool alanları:

Alan Tür Açıklama
start number Pool'daki ilk port (varsayılan: 8100)
end number Pool'daki son port (varsayılan: 8199)
allocated number[] Şu anda tahsis edilen portlar

Manuel Registry İşlemleri

Tüm registry'yi oku:

cat ~/.claude/worktree-registry.json | jq '.'

Tüm worktrees'i listele:

cat ~/.claude/worktree-registry.json | jq '.worktrees[]'

Belirli proje için worktrees'i listele:

cat ~/.claude/worktree-registry.json | jq '.worktrees[] | select(.project == "my-project")'

Tahsis edilen portları al:

cat ~/.claude/worktree-registry.json | jq '.portPool.allocated'

Dal'a göre worktree bul (kısmi eşleşme):

cat ~/.claude/worktree-registry.json | jq '.worktrees[] | select(.branch | contains("auth"))'

Manuel worktree girdisi ekle:

TMP=$(mktemp)
jq '.worktrees += [{
  "id": "'$(uuidgen)'",
  "project": "my-project",
  "repoPath": "/path/to/repo",
  "branch": "feature/auth",
  "branchSlug": "feature-auth",
  "worktreePath": "/Users/me/tmp/worktrees/my-project/feature-auth",
  "ports": [8100, 8101],
  "createdAt": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
  "validatedAt": null,
  "agentLaunchedAt": null,
  "task": "My task",
  "prNumber": null,
  "status": "active"
}]' ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json

Tahsis edilen pool'a portlar ekle:

TMP=$(mktemp)
jq '.portPool.allocated += [8100, 8101] | .portPool.allocated |= unique | .portPool.allocated |= sort_by(.)' \
  ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json

Worktree girdisini sil:

TMP=$(mktemp)
jq 'del(.worktrees[] | select(.project == "my-project" and .branch == "feature/auth"))' \
  ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json

Pool'dan portları serbest bırak:

TMP=$(mktemp)
jq '.portPool.allocated = (.portPool.allocated | map(select(. != 8100 and . != 8101)))' \
  ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json

Boş registry başlat (eksikse):

mkdir -p ~/.claude
cat > ~/.claude/worktree-registry.json << 'EOF'
{
  "worktrees": [],
  "portPool": {
    "start": 8100,
    "end": 8199,
    "allocated": []
  }
}
EOF

Manuel Port Tahsis

scripts/allocate-ports.sh başarısız olursa, portları manuel tahsis et:

Adım 1: Şu anda tahsis edilen portları al

ALLOCATED=$(cat ~/.claude/worktree-registry.json | jq -r '.portPool.allocated[]' | sort -n)
echo "Currently allocated: $ALLOCATED"

Adım 2: İlk mevcut portu bul (tahsis listesinde DEĞİL VE sistem tarafından kullanılmıyor)

for PORT in $(seq 8100 8199); do
  # Registry'de var mı kontrol et
  if ! echo "$ALLOCATED" | grep -q "^${PORT}$"; then
    # Sistem tarafından kullanılıyor mu kontrol et
    if ! lsof -i :"$PORT" &>/dev/null; then
      echo "Available: $PORT"
      break
    fi
  fi
done

Adım 3: Tahsis edilen pool'a ekle

TMP=$(mktemp)
jq '.portPool.allocated += [8100] | .portPool.allocated |= unique | .portPool.allocated |= sort_by(.)' \
  ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json

Sen (Claude) Neler Yaparsin vs Scriptler Neler Yapar

Görev Script Mevcut Manuel Geri Dönüş
Proje adını belirle Hayır git remote get-url origin veya basename $(pwd) parse et
Paket yöneticisini tespit et Hayır Lockfile'ları kontrol et (Tespit bölümüne bak)
Git worktree oluştur Hayır git worktree add <path> -b <branch>
.agents/ dizinini kopyala Hayır cp -r .agents <worktree-path>/
Bağımlılıkları kur Hayır Tespit edilen kurulum komutunu çalıştır
Doğrula (health check) Hayır Sunucuyu başlat, endpoint'i kontrol et, sunucuyu durdur
Portları tahsis et scripts/allocate-ports.sh 2 Manuel (yukarıya bak)
Worktree'yi kaydıt et scripts/register.sh Manuel jq (yukarıya bak)
Ajanı terminalde başlat scripts/launch-agent.sh Manuel (aşağıya bak)
Durumu göster scripts/status.sh cat ~/.claude/worktree-registry.json | jq ...
Worktree'yi temizle scripts/cleanup.sh Manuel (Temizleme bölümüne bak)

İş Akışları

1. Ajanlarla Birden Fazla Worktree Oluştur

Kullanıcı söyler: "3 worktree oluştur: feature/auth, feature/payments, fix/login-bug"

Sen yaparsın (alt ajanlarla paralel hale getirebilirsin):

HER DAL İÇİN (paralel çalıştırabilir):

1. KURULUM
   a. Proje adını al:
      PROJECT=$(basename $(git remote get-url origin 2>/dev/null | sed 's/\.git$//') 2>/dev/null || basename $(pwd))
   b. Repo kökünü al:
      REPO_ROOT=$(git rev-parse --show-toplevel)
   c. Dal'ı slug haline getir:
      BRANCH_SLUG=$(echo "feature/auth" | tr '/' '-')
   d. Worktree yolunu belirle:
      WORKTREE_PATH=~/tmp/worktrees/$PROJECT/$BRANCH_SLUG

2. PORTLARI TAHSIS ET
   Seçenek A (script): ~/.claude/skills/worktree-manager/scripts/allocate-ports.sh 2
   Seçenek B (manuel): 8100-8199 aralığından 2 kullanılmayan portu bul, registry'ye ekle

3. WORKTREE OLUŞTUR
   mkdir -p ~/tmp/worktrees/$PROJECT
   git worktree add $WORKTREE_PATH -b $BRANCH
   # Dal zaten varsa -b bayrağını çıkar

4. KAYDEDILMEMIŞ KAYNAKLARI KOPYALA
   cp -r .agents $WORKTREE_PATH/ 2>/dev/null || true
   cp .env.example $WORKTREE_PATH/.env 2>/dev/null || true

5. BAĞIMLILIKLARI KUR
   cd $WORKTREE_PATH
   # Tespit et ve çalıştır: npm install / uv sync / vb.

6. DOĞRULA (sunucuyu başlat, health check, durdur)
   a. Tahsis edilen portla sunucuyu başlat
   b. Bekle ve health kontrol et: curl -sf http://localhost:$PORT/health
   c. Sunucuyu durdur
   d. BAŞARISIZ OLURSA: hatayı raporla ama diğer worktrees'le devam et

7. GLOBAL REGISTRY'YE KAYDIT ET
   Seçenek A (script): ~/.claude/skills/worktree-manager/scripts/register.sh ...
   Seçenek B (manuel): ~/.claude/worktree-registry.json'u jq ile güncelle

8. AJANICI BAŞLAT
   Seçenek A (script): ~/.claude/skills/worktree-manager/scripts/launch-agent.sh $WORKTREE_PATH "task"
   Seçenek B (manuel): Terminali manuel aç, cd yap, claude çalıştır

TÜM TAMAMLANDIKTAN SONRA:
- Kullanıcıya özet tablosu raporla
- Herhangi bir hatayı detaylarıyla not et

2. Durumu Kontrol Et

Script ile:

~/.claude/skills/worktree-manager/scripts/status.sh
~/.claude/skills/worktree-manager/scripts/status.sh --project my-project

Manuel:

# Tüm worktrees
cat ~/.claude/worktree-registry.json | jq -r '.worktrees[] | "\(.project)\t\(.branch)\t\(.ports | join(","))\t\(.status)\t\(.task // "-")"'

# Geçerli proje için
PROJECT=$(basename $(git remote get-url origin 2>/dev/null | sed 's/\.git$//'))
cat ~/.claude/worktree-registry.json | jq -r ".worktrees[] | select(.project == \"$PROJECT\") | \"\(.branch)\t\(.ports | join(\",\"))\t\(.status)\""

3. Ajanı Manuel Başlat

launch-agent.sh başarısız olursa:

Ghostty için:

open -na "Ghostty.app" --args -e fish -c "cd '$WORKTREE_PATH' && claude"

iTerm2 için:

osascript -e 'tell application "iTerm2" to create window with default profile' \
  -e 'tell application "iTerm2" to tell current session of current window to write text "cd '"$WORKTREE_PATH"' && claude"'

tmux için:

tmux new-session -d -s "wt-$PROJECT-$BRANCH_SLUG" -c "$WORKTREE_PATH" "fish -c 'claude'"

4. Worktree'yi Temizle

Script ile:

~/.claude/skills/worktree-manager/scripts/cleanup.sh my-project feature/auth --delete-branch

Manuel temizleme:

# 1. Registry'den worktree bilgisini al
ENTRY=$(cat ~/.claude/worktree-registry.json | jq '.worktrees[] | select(.project == "my-project" and .branch == "feature/auth")')
WORKTREE_PATH=$(echo "$ENTRY" | jq -r '.worktreePath')
PORTS=$(echo "$ENTRY" | jq -r '.ports[]')
REPO_PATH=$(echo "$ENTRY" | jq -r '.repoPath')

# 2. Portlardaki işlemleri öldür
for PORT in $PORTS; do
  lsof -ti:"$PORT" | xargs kill -9 2>/dev/null || true
done

# 3. Worktree'yi kaldır
cd "$REPO_PATH"
git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || rm -rf "$WORKTREE_PATH"
git worktree prune

# 4. Registry'den kaldır
TMP=$(mktemp)
jq 'del(.worktrees[] | select(.project == "my-project" and .branch == "feature/auth"))' \
  ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json

# 5. Portları serbest bırak
TMP=$(mktemp)
for PORT in $PORTS; do
  jq ".portPool.allocated = (.portPool.allocated | map(select(. != $PORT)))" \
    ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json
done

# 6. İsteğe bağlı dal sil
git branch -D feature/auth
git push origin --delete feature/auth

5. Worktree'den PR Oluştur

Bir worktree dalından PR oluştururken, registry'yi PR numarasıyla güncelle:

# gh pr create başarılı olduktan sonra, PR numasını al
BRANCH=$(git branch --show-current)
PR_NUM=$(gh pr view --json number -q '.number')

# Registry'yi PR numarasıyla güncelle
if [ -n "$PR_NUM" ] && [ -f ~/.claude/worktree-registry.json ]; then
    TMP=$(mktemp)
    jq "(.worktrees[] | select(.branch == \"$BRANCH\")).prNumber = $PR_NUM" \
      ~/.claude/worktree-registry.json > "$TMP" && mv "$TMP" ~/.claude/worktree-registry.json
    echo "Updated worktree registry with PR #$PR_NUM"
fi

Bu, cleanup.sh --merged'in PR'ları birleştirdikten sonra otomatik olarak worktrees'leri bulması ve temizlemesini sağlar.

6. Registry'yi Senkronize Et

Registry'yi gerçek worktrees ve PR durumu ile uzlaştır:

# Durumu kontrol et (değişiklik yapma)
~/.claude/skills/worktree-manager/scripts/sync.sh

# Otomatik olarak sorunları düzelt (eksik girişleri kaldır, PR numaralarını güncelle)
~/.claude/skills/worktree-manager/scripts/sync.sh --fix

# Sessiz modu (sadece sorunları göster)
~/.claude/skills/worktree-manager/scripts/sync.sh --quiet

Paket Yöneticisi Tespiti

Öncelik sırasına göre lockfiles kontrol ederek tespit et:

Dosya Paket Yöneticisi Kurulum Komutu
bun.lockb bun bun install
pnpm-lock.yaml pnpm pnpm install
yarn.lock yarn yarn install
package-lock.json npm npm install
uv.lock uv uv sync
pyproject.toml (uv.lock yok) uv uv sync
requirements.txt pip pip install -r requirements.txt
go.mod go go mod download
Cargo.toml cargo cargo build

Tespit mantığı:

cd $WORKTREE_PATH
if [ -f "bun.lockb" ]; then bun install
elif [ -f "pnpm-lock.yaml" ]; then pnpm install
elif [ -f "yarn.lock" ]; then yarn install
elif [ -f "package-lock.json" ]; then npm install
elif [ -f "uv.lock" ]; then uv sync
elif [ -f "pyproject.toml" ]; then uv sync
elif [ -f "requirements.txt" ]; then pip install -r requirements.txt
elif [ -f "go.mod" ]; then go mod download
elif [ -f "Cargo.toml" ]; then cargo build
fi

Dev Sunucu Tespiti

Bu sırayla dev komutlarını ara:

  1. docker-compose.yml / compose.yml: docker-compose up -d veya docker compose up -d
  2. package.json scripts: dev, start:dev, serve ara
  3. uvicorn ile Python: uv run uvicorn app.main:app --port $PORT
  4. Flask ile Python: flask run --port $PORT
  5. Go: go run .

Port enjeksiyonu: Çoğu sunucu PORT env var'ını veya --port bayrağını kabul eder


Projeye Özgü Konfigürasyon (İsteğe Bağlı)

Projeler özel ayarlar için .claude/worktree.json sağlayabilir:

{
  "ports": {
    "count": 2,
    "services": ["api", "frontend"]
  },
  "install": "uv sync && cd frontend && npm install",
  "validate": {
    "start": "docker-compose up -d",
    "healthCheck": "curl -sf http://localhost:{{PORT}}/health",
    "stop": "docker-compose down"
  },
  "copyDirs": [".agents", ".env.example", "data/fixtures"]
}

Bu dosya varsa, ayarlarını kullan. Değilse, otomatik tespit et.


Paralel Worktree Oluşturma

Birden fazla worktree oluştururken, paralelleştirme için alt ajanları kullan:

Kullanıcı: "feature/a, feature/b, feature/c için worktrees oluştur"

Sen:
1. TÜM worktrees için portları önceden tahsis et (toplam 6 port)
2. 3 alt ajan başlat, worktree başına bir tane
3. Her alt ajan:
   - Worktree'sini oluştur
   - Bağımlılıkları kur
   - Doğrula
   - Önceden tahsis edilen portlarıyla kaydıt et
   - Ajanı başlat
4. Tüm alt ajanlardan sonuçları topla
5. Herhangi bir hatanın not edildiği birleştirilmiş özet raporla

Güvenlik Yönergeleri

  1. Temizlemeden önce, PR durumunu kontrol et:

    • PR birleştirildi → her şeyi temizlemek güvenli
    • PR açık → kullanıcıyı uyar, devam etmeden önce onayla
    • PR yok → gönderilmemiş iş hakkında uyar
  2. Dalları silmeden önce, şunları kontrol et:

    • PR birleştirilmedi mi
    • PR yok mu
    • Worktree kaydedilmemiş değişikliklere mi sahip
  3. Port çatışmaları: Port, worktree dışı bir işlem tarafından kullanılıyorsa, farklı port seç

  4. Yetim worktrees: Orijinal repo silinmişse, durumda orphaned olarak işaretle

  5. Maksimum worktrees: 100 portluk pool ve worktree başına 2 portla, ~50 eş zamanlı worktree mümkün


Script Referansı

Scriptler ~/.claude/skills/worktree-manager/scripts/ konumundadır

allocate-ports.sh

~/.claude/skills/worktree-manager/scripts/allocate-ports.sh <count>
# Döner: boşlukla ayrılmış port numaraları (ör. "8100 8101")
# Otomatik olarak registry'yi günceller

register.sh

~/.claude/skills/worktree-manager/scripts/register.sh \
  <project> <branch> <branch-slug> <worktree-path> <repo-path> <ports> [task]
# Örnek:
~/.claude/skills/worktree-manager/scripts/register.sh \
  "my-project" "feature/auth" "feature-auth" \
  "$HOME/tmp/worktrees/my-project/feature-auth" \
  "/path/to/repo" "8100,8101" "OAuth uygula"

launch-agent.sh

~/.claude/skills/worktree-manager/scripts/launch-agent.sh <worktree-path> [task]
# Yeni terminal penceresi açar (varsayılan olarak Ghostty) Claude Code ile

status.sh

~/.claude/skills/worktree-manager/scripts/status.sh [--project <name>]
# Tüm worktrees'leri göster, veya projeye göre filtrele

cleanup.sh

~/.claude/skills/worktree-manager/scripts/cleanup.sh <project> <branch> [--delete-branch]
# Portları öldür, worktree'yi kaldır, registry'yi güncelle
# --delete-branch aynı zamanda yerel ve uzak git dallarını da kaldırır

# Veya birleştirilen TÜM worktrees'leri bir kerede temizle:
~/.claude/skills/worktree-manager/scripts/cleanup.sh --merged [--delete-branch]
# Birleştirilen PR'lara sahip tüm worktrees'leri bulur ve temizler

sync.sh

~/.claude/skills/worktree-manager/scripts/sync.sh [--quiet] [--fix]
# Registry'yi gerçek worktrees ve PR durumuyla uzlaştır
# --quiet: Yalnızca sorunları göster, OK girişleri gösterme
# --fix: Otomatik olarak eksik girişleri kaldır ve PR numaralarını/durumunu güncelle

# Örnek: Hiçbir şey değiştirmeden durumu kontrol et
~/.claude/skills/worktree-manager/scripts/sync.sh

# Örnek: Registry sorunlarını otomatik düzelt
~/.claude/skills/worktree-manager/scripts/sync.sh --fix

release-ports.sh

~/.claude/skills/worktree-manager/scripts/release-ports.sh <port1> [port2] ...
# Portları pool'a geri serbest bırak

Beceri Konfigürasyonu

Konum: ~/.claude/skills/worktree-manager/config.json

{
  "terminal": "ghostty",
  "shell": "fish",
  "claudeCommand": "claude",
  "portPool": {
    "start": 8100,
    "end": 8199
  },
  "portsPerWorktree": 2,
  "worktreeBase": "~/tmp/worktrees",
  "defaultCopyDirs": [".agents", ".env.example"]
}

Benzer skill'ler

Daha fazla: Development →