デュアルモニターでコードを確認しながら作業するエンジニア
ニュース深掘り

Git worktreeでAIコーディングエージェントを並列実行する仕組み

目次を見る

Claude CodeやCodex、Gemini CLIといったコーディングエージェント(自然言語の指示からコードを書くCLIツール)を使っていて、「同時に2つのタスクを別のエージェントに振りたいのに、ターミナルを手作業で分けてブランチも自分で切っている」と感じたことがあるなら、Paradev(旧Superset)というオーケストレーション(複数の処理を調整・統括する仕組み)ツールの設計は参考になります。

Paradevはエージェントそのものではなく、既存のエージェントCLIを並列に動かすための土台です。Git worktree(1つのリポジトリから複数の作業ディレクトリを同時にチェックアウトできるGitの機能)を使い、タスクごとにファイルシステム・ブランチ・ターミナルセッションを丸ごと分離します。

Git worktreeが解決する「同じリポジトリの取り合い」問題

通常、1つの作業ディレクトリでGitを使うと、チェックアウトできるブランチは同時に1つだけです。エージェントAに機能追加を頼みながら、同じディレクトリでエージェントBにバグ修正を頼むと、ブランチの切り替えやファイルの上書きで作業が衝突します。

git worktree add コマンドを使うと、同一リポジトリの別ブランチを、別のディレクトリにチェックアウトできます。たとえば git worktree add ../feature-x feature-x とすれば、../feature-x という独立したディレクトリに新しいブランチの作業環境ができます。

Paradevはこの操作を自動化しています。新しいタスクを作成すると、裏側で次の処理が走ります。

  • 現在のHEAD(直前のコミット位置)から新しいブランチを作成する
  • そのブランチを新しいworktreeディレクトリにチェックアウトする
  • そのディレクトリでターミナルセッション(PTY、擬似端末)を立ち上げる
  • 指定したエージェントCLIをプロンプト付きで起動する

重要なのは、.git ディレクトリ自体はリポジトリ間で共有される点です。各worktreeは独立したファイルの実体を持ちますが、コミット履歴やブランチ情報は全worktreeから見えます。つまり「ファイルは隔離、履歴は共有」という設計です。

コンフリクトはいつ・どこで起きるのか

2つのエージェントが別々のworktreeで同じファイルを編集しても、作業中は衝突しません。それぞれが独立したチェックアウトを触っているからです。

コンフリクトが表面化するのは、ブランチをマージする瞬間です。Paradevはこの自動解決を試みません。コミット・プッシュしてPR(プルリクエスト)を作成すると、GitHubやGitLabがいつも通りマージコンフリクトを検出し、PR画面やエディタ上で人間が解消する流れになります。

この設計には明確なトレードオフがあります。新機能追加・バグ修正・リファクタリングのように独立したタスクには向いていますが、2つのエージェントが同じファイルをリアルタイムで協調編集する必要がある場合には向きません。そうしたケースでは、共有状態を持つメッセージパッシング方式や、逐次実行方式など別のオーケストレーションパターンが必要になります。

開発サーバーのポート競合という落とし穴

各worktreeは自分の開発サーバーを独立して起動できます。Paradevはターミナル出力を監視して http://localhost:3000 のようなURLパターンを検出し、自動的にアプリ内ブラウザプレビューを開きます。

ただし、2つのエージェントが同じポート番号(たとえば3000番)で待ち受けようとすると、後から起動した方は失敗します。Paradevはポート番号を自動で書き換える機能を持っていません。複数のタスクを並列実行する際は、開発サーバー側でポートを自動割り当てにするか、タスクごとに明示的に異なるポートを指定する設定が必要です。

ElectronアプリとしてのPTY管理・状態永続化

ParadevはTypeScript製バックエンドを持つElectronアプリ(Webフロントエンド技術でデスクトップアプリを作る仕組み)として実装されています。エージェントの実行状態は、PTY出力と終了コードを監視することで「実行中・入力待ち・完了」の3状態を判定します。

ワークスペースのメタデータ(worktreeのパス、ブランチ名、エージェントCLIのコマンド、最終ステータス、ターミナルのスクロールバック)はローカルのSQLiteデータベースに保存されます。アプリを再起動してもセッションを復元できる設計です。

既存の並列開発手法との比較で見えること

Git worktree自体はGit 2.5(2015年リリース)から存在する機能で、目新しいものではありません。これまでは、複数ブランチの並行作業や、長時間のビルドを別ブランチで走らせたい場面で手動利用されてきました。

Paradevの価値は、この既存機能を「AIエージェントの並列実行」というユースケースに合わせて自動化した点にあります。似た発想として、コンテナ(Dockerなど)でタスクごとに実行環境を分離する方法もありますが、コンテナは起動コストがworktreeより重く、ホストのファイルシステムとの往復も複雑になりがちです。worktreeはファイルシステムレベルの軽量な分離なので、ローカル開発でのエージェント並列実行とは相性が良い設計と言えます。

今日確認できること

自分の環境でこの仕組みが活用できそうか判断するには、次を確認してみてください。

  • git --version でGit 2.5以上か確認する(worktreeコマンドの前提条件)
  • 普段使っているエージェントCLI(Claude Code、Codex、OpenCode、Gemini CLI、Cursor Agentなど)がCLIとして単独起動できるか確認する
  • 開発サーバーの起動設定でポート番号がハードコードされていないか、環境変数等で変更可能かを確認する
  • 並列化したいタスクが「独立したファイル群を触る作業」か「同一ファイルの協調編集」かを見極める(後者は worktree 単体では解決しない)

まず手元で git worktree add ../test-branch -b test-branch を試し、別ディレクトリでエージェントCLIを動かしてみると、Paradevが自動化している処理の実感が掴みやすくなります。

まとめ

Paradevの核心は、新しいエージェントではなく「既存のGit worktree機能をAIエージェントの並列実行向けに自動化したオーケストレーション層」である点です。

ファイルシステムはタスクごとに分離されますが、.git は共有されるため、コンフリクトはマージ時に初めて表面化します。ポート競合や同一ファイルの協調編集のように自動化されていない領域も明確にあります。

導入を検討するなら、まず自分の手で git worktree コマンドを試し、分離の範囲と限界を体感してから、自動化ツールに任せる部分を決めるのが確実な進め方です。

参考

Paradev's Parallel Agent Orchestration: How Git Worktrees Let Multiple Coding Agents Work the Same Repo Without Colliding

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。