claude-code-merge-queue: 並列AIエージェント向けローカルマージキュー

並列AIエージェントのためのローカルシリアライズ

claude-code-merge-queue は、単一のコードベースで作業する複数の並列 Claude Code エージェントを管理するために設計された、ローカルかつゼロコストのマージキューです。プッシュ競合、冗長な重いビルド、共有リソースによるテストの不安定さといった一般的な同時実行問題を、コード変更の着手、ビルド、テストのプロセスを直列化することで防止します。

クラウドベースのマージキューとは異なり、このツールは開発者のローカルマシン上で完全に実行されるため、エンタープライズプランの有料利用や GitHub Actions の分数をキューの試行ごとに必要としません。

コア機能とコマンド

このツールは Claude Code のネイティブな worktree 作成と直接統合され、エージェント主導の変更のライフサイクルを管理する一連のコマンドを提供します。

着手と同期

  • land: FIFO キューを介してレーンを統合ブランチにリベースしプッシュします。これにより、2 つのエージェントが同時にプッシュしようとすることはありません。
  • sync: 最新の着手済み変更を反映するようにメインのチェックアウトを早送りし、ロックファイルが変更された場合は依存関係を再インストールします。
  • promote: 人間のみが使用するコマンドで、統合ブランチを本番環境へデプロイします。エージェントの指示からは明示的に除外されており、自動的な本番デプロイを防止します。

開発と保守

  • build-lock: 指定されたビルドコマンドをマシン上のすべてのレーンで直列に実行し、リソース競合を防止します。
  • preview: レーンのライブ作業ツリー（未コミットの変更を含む）をメインのチェックアウトにミラーリングし、フルビルドを必要とせずに即座に人間が検査できるようにします。
  • port: ディレクトリ名に基づいて特定のレーンの開発サーバーポートを計算し表示します。
  • prune: すでに着手済みのレーンから worktree をクリーンアップします。

技術実装とガードレール

設定とセットアップ

npx claude-code-merge-queue init による初期化は、claude-code-merge-queue.config.mjs ファイルを作成し、テストが合格したらエージェントが自分の作業を着手するよう指示するために CLAUDE.md を更新することで環境を構成します。また、.claude/settings.json に WorktreeCreate フックを組み込み、（利用可能な場合は Husky を通じて）プリプッシュフックを設定し、保護ブランチへの直接 git push の代わりに land が使用されるようにします。

安全メカニズム

  • The Emergency Hatch: 保護ブランチへのブロックを回避するため、ユーザーは git push 時に環境変数 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 を使用できます。これはセキュリティ境界というよりは慣例に基づくガードレールです。
  • Crash-Safe Locking: ロックは PID の存続で管理されます。プロセスが終了（例: kill -9）した場合、次のプロセスが死んだ PID を検知してロックを再取得し、タイムアウトの必要がなくなります。
  • Conflict Handling: land プロセス中にリベースコンフリクトが発生した場合、ツールは git rebase --abort を実行し、作業ツリーをクリーンな状態にします。その後、エージェントは CLAUDE.md に従ってコンフリクトを解消し、コマンドを再実行するよう指示されます。

比較: ローカル vs. クラウド マージキュー

機能 GitHub マージキュー Claude Code マージキュー
プライベートリポジトリのサポート Enterprise Cloud のみ すべてのプラン、すべてのリポジトリ
コスト 試行ごとの GitHub Actions 分数 $0（ローカル実行）
要件 プルリクエストが必要 直接リベース + プッシュ

制約と限界

  • Lack of Human Review: checkCommand（例: npm run check）が唯一のゲートです。コマンドが成功すればコードは着手されます。マージ前に人間の承認を得る組み込みメカニズムはありません。
  • Single-Machine Scope: FIFO キューはローカルの一時ストレージに保存されます。複数のマシンが同時に変更を着手しようとすると、標準的な Git の non-fast-forward 拒否に遭遇します。
  • Throughput Ceiling: 1 時間あたりの着手回数は checkCommand の実行時間に依存します。たとえば 4 分のテストスイートの場合、1 時間に 20 回未満に制限されます。
  • Security: このツールはセキュリティ境界ではありません。シェルアクセスを持つユーザーは git push --no-verify を使用してフックを回避できます。

コミュニティの見解

コミュニティのユーザーは、エージェントの同時実行管理の代替アプローチとして、Git の代わりに jj（Jujutsu）を使用して worktree やブランチをより柔軟に扱う方法や、コンテンツベースのダイジェストを利用して冗長なテストを回避するカスタムデプロイシステムの実装を提案しています。小規模な運用では、会話ごとに分離された worktree とオーケストレータエージェントを組み合わせることで、専用のマージキュー ツールなしでも同様の結果が得られると指摘する開発者もいます。

Sources