スーパーリポとClaude Codeが最良のワークツリー管理ツールである理由
ワークロードごとに適した並列化の方法は異なります。通常のGit変更にはワークツリーが向いています。サブモジュールやビルドツールがワークツリーを扱いにくい場合は、複数のチェックアウトが役立ちます。E2B、Freestyle、Daytona、Modalはリモートサンドボックスを提供し、GitHub Actionsも同じ用途に転用できます。ローカルの分離にはDocker、UTM、Lima、OrbStackがあります。Mac miniやLinuxマシンを並べるチームもあります。ML実験にはRay、Modal、Slurmが適しています。mainですべてを一気に進めるのが最速な場合もあります。
役に立つマネージャーは、タスクの文脈からこれらの実行方式を選ぶべきです。これはcmuxの禅に沿っています。プリミティブを組み合わせ可能なままにして、使い方はプロジェクトのルールに決めさせます。
スーパーリポはプロジェクトの司令部
この制御用リポジトリをスーパーリポと呼びたいと思います。コーディングエージェントにとって、スーパーリポは一つ以上のソースリポジトリの上位にあり、プロンプトを分離されたタスク環境へ変換するためのデータ、スキル、origin、ワークツリー、運用ルールを保持します。
~/my-superrepo/
├── AGENTS.md
├── skills/
├── data/
├── origins/
│ └── [repo]/
└── worktrees/
└── [task]/
└── [repo]/AGENTS.mdが制御プレーンです。エージェントが必要とする可能性のあるリポジトリ、各タスクのワークツリーを置く場所、リポジトリごとのセットアップ手順を定義します。一つのタスクでターミナル、ブラウザ連携、ルーター用の対応するワークツリーを作れますが、すべてのタスクで三つとも複製する必要はありません。
cmux-hqで作業しています。タスクには次のリポジトリが関係する場合があります：
- manaflow-ai/cmux
- manaflow-ai/cmux-browser
- manaflow-ai/coderouter
ユーザーが新しいタスクを依頼したとき：
1. タスクに必要なリポジトリを判断します。
2. worktrees/[task]/[repo]に対応するワークツリーを作成します。
3. 各ワークツリーのAGENTS.mdを読みます。
4. セットアップスクリプトをすぐに起動し、タスクを続けます。トポロジーをエージェントに選ばせる
cmuxではこのパターンを社内で使っています。公開ソースはmanaflow-ai/cmuxにあり、非公開の制御用リポジトリはmanaflow-ai/cmuxterm-hqです。hqのルートから、cmuxにも関係する可能性があるCodeRouterの問題をCodexやClaude Codeに依頼できます。エージェントは必要なワークツリーだけを作り、各リポジトリのAGENTS.mdを読み、セットアップスクリプトを起動し、その実行中にコードの調査を始めます。
cd ~/fun/cmux-hq
codex --yolo "CodeRouterのxyz問題を修正して。cmuxのxyzにも関係する可能性あり"./scripts/new-worktree.shは一つのトポロジーを実装します。エージェントなら、互換性のないサブモジュールには別チェックアウト、信頼できないセットアップにはリモートサンドボックス、別OSにはVM、実験にはGPUスケジューラを選び、決定的な処理には既存のスクリプトを再利用できます。
完了までの時間が短くなる理由
多くのプロジェクトでは、ワークツリーは並列化の一部にすぎません。MLでは、一つのコーディングエージェントが一つのワークツリーで複数の実験を書き、スケジューラが実行を複数のGPUへ配布できます。ワークツリーを増やしても計算資源は増えず、調整だけが増えます。
エージェントによるオーケストレーションは起動時間も短縮できます。チェックアウトができた時点でエージェントはコードを読み書きし、依存関係のインストール、ビルド、ローカルサービスの起動はバックグラウンドで続けられます。すべてのセットアップ完了後にエージェントを起動するラッパーでは、最も遅い前提処理がクリティカルパスに入ります。
トレードオフ
Claude CodeやCodexをマネージャーとして使うと、リポジトリ構成の理解に追加のトークンとコンテキストウィンドウを使います。単一のチェックアウト内ではなくスーパーリポのルートから始める形にも慣れが必要なので、指示は明確でなければなりません。cmuxは、その指示から呼び出せるカスタムコマンド、プログラム可能なCLIとソケットAPI、再利用可能なスキルを提供します。
私たちにとって、その柔軟性にはコストを払う価値があります。cmux homeがワークフローの操作面を提供し、スーパーリポがタスクごとの組み立て方をエージェントへ伝えます。最高のワークツリーマネージャーは、ワークツリーが並列化の単位として不適切な場面も判断できます。