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 mkdir -p ~/.claude/skills/worktree-manager
curl -fsSL https://raw.githubusercontent.com/Wirasm/worktree-manager-skill/HEAD/.claude/skills/SKILL.md \
-o ~/.claude/skills/worktree-manager/SKILL.md 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.
Tetikleme ifadeleri:
| 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 |
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/
Dal adları dosya sistemi güvenliği için / yerine - konularak slug haline getirilir:
feature/auth → feature-authfix/login-bug → fix-login-bugfeat/user-profile → feat-user-profileManuel slug haline getir: echo "feature/auth" | tr '/' '-' → feature-auth
lsof -i :<port>~/.claude/worktree-registry.json
{
"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]
}
}
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 |
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
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
| 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) |
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
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)\""
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'"
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
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.
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
Ö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
Bu sırayla dev komutlarını ara:
docker-compose up -d veya docker compose up -ddev, start:dev, serve arauv run uvicorn app.main:app --port $PORTflask run --port $PORTgo run .Port enjeksiyonu: Çoğu sunucu PORT env var'ını veya --port bayrağını kabul eder
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.
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
Temizlemeden önce, PR durumunu kontrol et:
Dalları silmeden önce, şunları kontrol et:
Port çatışmaları: Port, worktree dışı bir işlem tarafından kullanılıyorsa, farklı port seç
Yetim worktrees: Orijinal repo silinmişse, durumda orphaned olarak işaretle
Maksimum worktrees: 100 portluk pool ve worktree başına 2 portla, ~50 eş zamanlı worktree mümkün
Scriptler ~/.claude/skills/worktree-manager/scripts/ konumundadır
~/.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
~/.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"
~/.claude/skills/worktree-manager/scripts/launch-agent.sh <worktree-path> [task]
# Yeni terminal penceresi açar (varsayılan olarak Ghostty) Claude Code ile
~/.claude/skills/worktree-manager/scripts/status.sh [--project <name>]
# Tüm worktrees'leri göster, veya projeye göre filtrele
~/.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
~/.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
~/.claude/skills/worktree-manager/scripts/release-ports.sh <port1> [port2] ...
# Portları pool'a geri serbest bırak
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"]
}
2 veya daha fazla bağımsız görevin paralel olarak yürütülebileceği ve aralarında state paylaşımı ya da sıralı bağımlılık olmadığı durumlarda kullanın.
Ayrı bir oturumda inceleme kontrol noktaları ile yürütülecek yazılı bir uygulama planınız olduğunda kullanın.
Mevcut oturumda bağımsız görevlerle uygulama planlarını yürütürken kullanın
Herhangi bir hata, test başarısızlığı veya beklenmeyen davranışla karşılaştığınızda, çözüm önerisi sunmadan önce kullanın.
Herhangi bir feature ya da bugfix uygulamaya başlamadan önce kullanın.
Yeni beceriler oluştururken, mevcut becerileri düzenlerken veya dağıtımdan önce becerileri doğrularken kullanın.