worktree-manager

Claude Code エージェントと git worktree を使用して、すべてのプロジェクトにわたる並行開発を管理します。各 worktree は異なるブランチ上のリポジトリの分離されたコピーであり、`~/tmp/worktrees/` に集中的に保存されます。これにより、複数のエージェントが競合することなく同時に作業できます。

<quick_start> エージェントを使用して単一の worktree を作成する:

/worktree create feature/auth

Claude は次のことを行います:

1. ポートを割り当てる (8100-8101)
2. ~/tmp/worktrees/[project]/feature-auth に worktree を作成する
3. 依存関係をインストールする
4. エージェント用の WORKTREE_TASK.md を作成する
5. Claude Opus 4.6 エージェントでターミナルを起動する </quick_start>

ネイティブの --worktree フラグ (Claude Code v2.1.49+)

Claude Code には worktree のサポートが組み込まれました:

# Named worktree
claude --worktree feature-auth   # or: claude -w feature-auth

# Auto-generated name
claude -w

動作内容

• <repo>/.claude/worktrees/<name>/ に worktree を作成します
• ブランチ: worktree-<name> (デフォルトのリモートブランチから自動作成)
• 終了時: 変更がなければ自動クリーンアップ、変更があれば保持/削除を確認

ヒント: .claude/worktrees/ を .gitignore に追加してください

ネイティブ機能とこのスキルの使い分け

シナリオ	使用するもの
迅速な分離作業、単一エージェント	claude -w feature-name
マルチエージェントチーム、ポート割り当て、レジストリ	このスキル (worktree-manager)
サブエージェントの分離	Task ツールパラメータの isolation: "worktree"
非 git VCS (Perforce、SVN)	WorktreeCreate/WorktreeRemove フック

WorktreeCreate / WorktreeRemove フック

VCS に依存しない worktree ライフサイクルのための新しいフックイベントです。設定すると、デフォルトの git worktree の動作を置き換えます:

{
  "hooks": {
    "WorktreeCreate": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); NAME=$(echo \"$INPUT\" | jq -r .name); mkdir -p /tmp/worktrees/$NAME && echo $NAME'"
      }]
    }],
    "WorktreeRemove": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); PATH=$(echo \"$INPUT\" | jq -r .path); rm -rf $PATH'"
      }]
    }]
  }
}

フックとネイティブ機能の使い分け: 非 git の VCS システムで作業する場合や、カスタムの分離ロジック (例: Docker コンテナ、リモート開発サーバー) が必要な場合はフックを使用します。標準的な git リポジトリでは、ネイティブの claude -w フラグまたはこのスキルのワークフローが推奨されます。

注記: これらのフックはマッチャーをサポートしていません。worktree のライフサイクルイベントごとに 1 回発火します。フックは stdin の JSON を介して {name, path} を受け取ります。

<success_criteria> worktree のセットアップは次の場合に成功です:

• worktree が ~/tmp/worktrees/[project]/[branch-slug] に作成されている
• ポートが割り当てられ、グローバルに登録されている
• 依存関係がインストールされている
• エージェントがターミナル (Ghostty/iTerm2/tmux) で起動されている
• ~/.claude/worktree-registry.json にエントリが追加されている </success_criteria>

<current_state> Git リポジトリ: !git status --short --branch 2>/dev/null

既存の worktree: !git worktree list 2>/dev/null

worktree レジストリ: !cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | "\(.project)/\(.branch) → \(.status)"' | head -10

利用可能なポート: !cat ~/.claude/worktree-registry.json 2>/dev/null | jq '.portPool.allocated | length' || echo "0" 割り当て済み </current_state>

<activation_triggers>

このスキルが有効になるタイミング

トリガーフレーズ:

• 「X、Y、Z の worktree を立ち上げて」
• 「機能 A、B、C 用に 3 つの worktree を作成して」
• 「feature/auth 用の新しい worktree」
• 「私の worktree の状態は?」
• 「すべての worktree を表示」/「このプロジェクトの worktree を表示」
• 「マージ済みの worktree をクリーンアップして」
• 「worktree X でエージェントを起動して」

呼び出し

コマンド構文:

• /worktree create feature/auth - 単一の worktree
• /worktree create feat1 feat2 feat3 - 複数の worktree
• /worktree status - すべての worktree を確認
• /worktree status --project myapp - プロジェクトで絞り込み
• /worktree cleanup feature/auth - worktree を削除
• /worktree launch feature/auth - worktree でエージェントを起動

</activation_triggers>

<file_locations>

主要ファイル

ファイル	目的
~/.claude/worktree-registry.json	グローバルレジストリ - すべてのプロジェクトにわたるすべてのワークツリーを追跡します
~/.claude/skills/worktree-manager/config.json	スキル設定 - ターミナル、シェル、ポート範囲の設定
~/.claude/skills/worktree-manager/scripts/	ヘルパースクリプト - オプション、すべて手動で実行可能
~/tmp/worktrees/	ワークツリーストレージ - すべてのワークツリーはここに保存されます
.claude/ (プロジェクトごと)	プロジェクト設定 - CLAUDE.md、フック、権限、カスタムエージェント
.claude/worktree.json (プロジェクトごと)	プロジェクト設定 - オプションのカスタム設定
WORKTREE_TASK.md (ワークツリーごと)	自動読み込みタスクプロンプト - エージェントが起動時に読み込みます

</file_locations>

<core_concepts>

中核となる概念

集中管理されたワークツリーストレージ

すべてのワークツリーは ~/tmp/worktrees/<project-name>/<branch-slug>/ に保存されます

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

ブランチスラッグの規則

ブランチ名はファイルシステムの安全性のためにスラッグ化されます:

• feature/auth → feature-auth
• fix/login-bug → fix-login-bug

手動でスラッグ化: echo "feature/auth" | tr '/' '-'

ポート割り当て

• グローバルプール: 8100-8199 (合計 100 ポート)
• ワークツリーごと: 2 ポートを割り当て (API + フロントエンドのパターン用)
• グローバルに一意: プロジェクト間の競合を避けるためにポートを追跡します

参照: 詳細な操作については reference/port-allocation.md を参照してください。

必須のデフォルト

重要: エージェントを起動する際には、これらの設定を必ず使用してください:

設定	値	理由
ターミナル	Ghostty または iTerm2	自動検出、config.json で設定可能
モデル	--model opus	Opus 4.6 エイリアス (最も高性能)
フラグ	--dangerously-skip-permissions	自律的なファイル操作に必要

起動コマンドのパターン:

# Recommended: agent inherits .claude/ config (CLAUDE.md, hooks, permissions)
claude --model opus --dangerously-skip-permissions

# Or with explicit permission allowlist (safer, from .claude/settings.json):
claude --model opus --allowedTools "Bash(npm test),Bash(npm run build),Edit,Write,Read,Glob,Grep"

サブエージェントのワークツリー分離

サブエージェントは、分離されたワークツリーで実行するように構成できます:

# In subagent frontmatter:
---
name: my-subagent
isolation: worktree
---

サブエージェントは一時的なワークツリーで実行されます。完了時:

• 変更がない場合: 自動クリーンアップ
• 変更がある場合: 変更はレビュー用に保持されます

</core_concepts>

スキル設定

場所: ~/.claude/skills/worktree-manager/config.json

{
  "terminal": "ghostty",
  "terminalPreference": "auto",
  "enableNumberedTabs": true,
  "shell": "zsh",
  "defaultModel": "opus",
  "claudeCommand": "claude --model opus --dangerously-skip-permissions",
  "portPool": { "start": 8100, "end": 8199 },
  "portsPerWorktree": 2,
  "worktreeBase": "~/tmp/worktrees",
  "defaultCopyDirs": [".claude"],
  "envFilePriority": [".env.local", ".env", ".env.example"],
  "autoCleanupOnMerge": true
}

.claude/ ディレクトリの伝播

ワークツリーを作成する際、.claude/ ディレクトリ全体がコピーされるため、エージェントはプロジェクトレベルの設定を継承します:

.claude/
├── CLAUDE.md              # Project instructions (auto-loaded by Claude Code)
├── settings.json          # Hooks and permissions
│   ├── hooks.PostToolUse  # Auto-format on Write|Edit (e.g., "bun run format || true")
│   └── permissions.allow  # Whitelisted bash commands for agents
├── agents/                # Custom subagent definitions
│   ├── build-validator.md # Validates builds pass
│   ├── code-architect.md  # Plans implementation
│   ├── code-simplifier.md # Refactors for clarity
│   └── verify-app.md      # End-to-end verification
└── PROJECT_CONTEXT.md     # Session continuity (project-context-skill)

これが重要な理由:

• CLAUDE.md: エージェントがプロジェクトの規約、開発コマンド、技術スタックを読み込みます
• フック: すべての Write/Edit 後に自動フォーマットが実行され、エージェント間でコードの一貫性が保たれます
• 権限: エージェントはプロンプトなしで事前承認されたコマンドを実行できます (例: npm test、bun run build)
• カスタムエージェント: エージェントはサブエージェントをディスパッチできます (例: エンドツーエンドチェック用の verify-app.md)

フックの例 (settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bun run format || true" }]
      }
    ]
  }
}

ワークフロー

複数のワークツリーを作成する

ユーザーの発言: 「feature/auth、feature/payments、fix/login-bug の 3 つのワークツリーを立ち上げて」

実行内容 (サブエージェントで並列化可能):

For EACH branch (can run in parallel):

1. SETUP
   PROJECT=$(basename $(git remote get-url origin 2>/dev/null | sed 's/\.git$//') || basename $(pwd))
   REPO_ROOT=$(git rev-parse --show-toplevel)
   BRANCH_SLUG=$(echo "feature/auth" | tr '/' '-')
   WORKTREE_PATH=~/tmp/worktrees/$PROJECT/$BRANCH_SLUG

2. ALLOCATE PORTS
   Find 2 unused ports from 8100-8199, add to registry

3. CREATE WORKTREE
   mkdir -p ~/tmp/worktrees/$PROJECT
   git worktree add $WORKTREE_PATH -b $BRANCH

4. COPY PROJECT CONFIG (.claude/ directory)
   cp -r .claude $WORKTREE_PATH/ 2>/dev/null || true
   Copy .env.local or .env as appropriate

5. CREATE WORKTREE_TASK.md
   Create detailed task file for agent

6. INSTALL DEPENDENCIES
   Detect package manager, run install command

7. VALIDATE (optional)
   Start server, health check, stop

8. REGISTER IN GLOBAL REGISTRY
   Update ~/.claude/worktree-registry.json with entry

9. LAUNCH AGENT
   ghostty -e "cd $WORKTREE_PATH && claude --model opus --dangerously-skip-permissions"

AFTER ALL COMPLETE:
- Report summary table to user

ステータスを確認する

スクリプトを使用する場合:

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

手動の場合:

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

ワークツリーをクリーンアップする

参照: 完全なクリーンアップ手順については reference/cleanup-operations.md を参照してください。

クイッククリーンアップ:

~/.claude/skills/worktree-manager/scripts/cleanup.sh <project> <branch> --delete-branch

参照ファイル

詳細な操作については、以下を参照してください:

トピック	ファイル
レジストリ操作	reference/registry-operations.md
ポート割り当て	reference/port-allocation.md
エージェントの起動	reference/agent-launching.md
システム通知	reference/system-notifications.md
スクリプトリファレンス	reference/script-reference.md
クリーンアップ操作	reference/cleanup-operations.md
高度なワークフロー	reference/advanced-workflows.md
トラブルシューティング	reference/troubleshooting.md

<safety_guidelines>

安全ガイドライン

1. クリーンアップの前に、PR の状態を確認してください：

   • PR がマージ済み → すべて安全にクリーンアップできます
   • PR がオープン → ユーザーに警告し、続行前に確認してください
   • PR がない → 未提出の作業があることを警告してください

2. ブランチを削除する前に、次の場合は確認してください：

   • PR がマージされていない
   • PR が存在しない
   • ワークツリーに未コミットの変更がある

3. ポートの競合：ワークツリー以外のプロセスがポートを使用している場合は、別のポートを選んでください

4. 環境ファイル：.env や .env.local を git にコミットしないでください

</safety_guidelines>

<example_session>

セッションの例

ユーザー：「feature/dark-mode と fix/login-bug 用に 2 つのワークツリーを立ち上げて」

あなた：

1. プロジェクトを検出：obsidian-ai-agent（git remote から）
2. パッケージマネージャーを検出：uv（uv.lock を検出）
3. 4 つのポートを割り当て：8100 8101 8102 8103
4. ワークツリーを作成：

   git worktree add ~/tmp/worktrees/obsidian-ai-agent/feature-dark-mode -b feature/dark-mode
   git worktree add ~/tmp/worktrees/obsidian-ai-agent/fix-login-bug -b fix/login-bug
   

5. .claude/ と .env を各ワークツリーにコピー
6. 依存関係をインストール：(cd <path> && uv sync)
7. 両方を ~/.claude/worktree-registry.json に登録
8. エージェントを起動：

   ghostty -e "cd ~/tmp/worktrees/.../feature-dark-mode && claude --model opus --dangerously-skip-permissions"
   

9. 報告：

   Created 2 worktrees with agents:
   
   | Branch | Ports | Path | Task |
   |--------|-------|------|------|
   | feature/dark-mode | 8100, 8101 | ~/tmp/worktrees/.../feature-dark-mode | Implement dark mode |
   | fix/login-bug | 8102, 8103 | ~/tmp/worktrees/.../fix-login-bug | Fix login redirect |
   
   Both agents running in Ghostty windows.
   

</example_session>

---

Boris Cherny のワークフローとの統合

iTerm2 の通知、Web セッションの引き継ぎ（/teleport）、自律セッション向けの ralph-loop、日次ワークフロープロトコルに対応しています。

iTerm2 の設定、teleport による引き継ぎ、ralph-loop のパターン、ターミナル戦略、日次ワークフロープロトコルについては、reference/advanced-workflows.md を参照してください。

結果サイドカーの出力

最後の手順として、~/.claude/skill-analytics/last-outcome-worktree-manager.json に書き込みます：

{"ts":"[UTC ISO8601]","skill":"worktree-manager","version":"1.2.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"worktrees_created":[n],"agents_launched":[n],"worktrees_cleaned":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージに失敗しても結果が生成されている場合は、ステータスに "partial" を使用してください。出力が生成されなかった場合にのみ "error" を使用してください。