git worktree で AI コーディングエージェントを並列に走らせる｜agent-start の分離戦略

agent-start は、claude / codex の CLI セッションをブラウザから起動・管理できるセルフホスト型ランチャーです (全体設計は前回の記事を参照)。

今回は、その中でも実用上とても効く機能、git worktree によるセッション分離を取り上げます。

問題: 並列エージェントは作業ツリーを奪い合う

AI コーディングエージェントを使い始めると、すぐに「同じリポジトリで複数のエージェントを同時に走らせたい」という欲求が出てきます。たとえば 1 つはバグ修正、もう 1 つはリファクタリング、といった具合です。

ところが、git の作業ツリー(working tree)はチェックアウト中のブランチと 1:1 です。同じディレクトリで 2 体のエージェントが別々の変更を始めると、

片方の git checkout がもう片方の未コミット変更を巻き込む
ビルド成果物や一時ファイルが衝突する
どちらの差分か分からなくなる

といった事故が起きます。「並列で走らせたいが、互いに踏み合ってほしくない」のです。

解決: セッションごとに git worktree を切る

git worktree は、1 つのリポジトリから 複数の作業ツリーを別ディレクトリに展開できる git の標準機能です。共有するのは .git のオブジェクトだけで、作業ツリーとチェックアウトブランチはそれぞれ独立します。

agent-start は、セッション作成時に --worktree を付けると、そのセッション専用の worktree を切ってその中でエージェントを起動します。

# CLI から: worktree 分離付きでセッションを作成
agent-start session create \
  --project /path/to/project \
  --cli claude \
  --worktree

UI からも同じことができ、--dangerously-skip-permissions / --full-auto などの起動フラグもチェックボックスで指定・保存できます。

flowchart TD
    Repo[(リポジトリ /projects/app)]
    Repo --> WT1[worktrees/session-A<br/>branch: agent/session-A]
    Repo --> WT2[worktrees/session-B<br/>branch: agent/session-B]
    WT1 --> A1[claude セッション A]
    WT2 --> A2[codex セッション B]

各エージェントは自分の worktree の中だけで作業するため、未コミット変更もビルド成果物も衝突しません。 worktree は次の場所に作られます(AGENT_START_WORKTREE_ROOT で変更可)。

~/.agent-start/worktrees/<session>/

停止時の後始末

worktree 方式の地味だが重要な利点が、後始末のしやすさです。セッションを停止すると、agent-start はその worktree を片付け、 そのセッションが乗っていたブランチごと削除します。

agent-start session stop <name>
# → worktree を削除し、そのブランチも掃除する

手作業で git worktree add を散らかすと、git worktree prune やブランチ削除を忘れてゴミが溜まりがちです。セッションのライフサイクル(作成→実行→停止)に worktree のライフサイクルを束ねることで、「使い終わったら綺麗に消える」状態を保てます。

なぜこの設計が効くのか

sequenceDiagram
    participant U as ユーザー
    participant H as agent-start-host
    participant G as git
    U->>H: session create --worktree
    H->>G: git worktree add(専用ブランチ)
    G-->>H: 隔離された作業ツリー
    H->>H: PTY で claude / codex を起動
    Note over H: 別セッションは別 worktree で並走
    U->>H: session stop
    H->>G: worktree 削除 + ブランチ削除

並列性: セッションごとに作業ツリーが独立するので、何体でも同時に走らせられる
安全性: 変更が混ざらず、差分がセッション＝ブランチ単位で明確
クリーンさ: 停止＝worktree とブランチの破棄。リポジトリが汚れない

PTY セッションを「ブラウザを閉じても生き続ける永続プロセス」として扱う agent-start の設計 (前回記事)と組み合わさることで、「複数エージェントを立てて放置し、あとで結果を回収する」という使い方が現実的になります。

まとめ

同一リポジトリでの並列エージェントは作業ツリーの衝突を起こす
agent-start は --worktree で セッション専用の git worktree + ブランチを切って分離
停止時に worktree とブランチをまとめて後始末するので、リポジトリが汚れない

セルフホストで AI エージェントを使い倒したい人は、ぜひ agent-start を試してみてください。