Mergetrain

mergetrain

並行するコーディングエージェントがコミットしたブランチを安全に統合します。

mergetrain は、並行する LLM エージェント向けのローカルなマージキューです。これらのコーディングエージェントは大規模言語モデルを使い、Git ワークツリーで作業します。mergetrain はお使いのマシン上で動作します。トレインとは、キューに登録されたタスクブランチのグループです。ゲートとは、設定済みのテストまたはチェックです。各エージェントがブランチをコミットしてキューに登録します。1 つのランナーが登録順にブランチをマージし、統合後の結果に対してゲートを実行します。明示的な承認を得た後に限り、Git の参照をアトミックに更新します。

mergetrain は、ローカルリポジトリを管理する 1 人のオペレーター向けに設計されています。

mergetrain のアカウント、ホスト型コントロールプレーン、OAuth アプリ、製品テレメトリーはありません。キューとランナーの状態はお使いのマシン上に保持されます。設定した Git リモートと、信頼できるゲートまたは検証コマンドのみが外部サービスに接続する場合があります。

修正中も開発を続ける

デフォルトのバッチモード：合格した作業を先に反映します。 修正が必要な作業はエージェントに差し戻されます。修正を続けている間も、合格した作業を反映できます。

チェック中も開発を続ける。 mergetrain が先行する作業をチェックしている間に、エージェントは次のタスクを開始します。この 14 秒のループでは、同じ 4 つのエージェントの動きを確認できます。

どちらのモードでも、エージェントは開発を続けられます。順序モードでは、先行する未解決の提出があると、後続の反映が保留されます。 2 つのモードを比較。

デモを一時停止または再生 · 静止画を表示 · 連続ワークフローを再現

このデモの作成方法

この図は記録された CLI の結果に基づいています。 4 つのレーンはエージェントの役割を表し、文字は作業を示します。キュージョブ ID ではありません。 キャプチャスクリプトは、使い捨てのローカルリポジトリとベアリモートで、エージェントが作成した変更とオペレーターの承認を記録します。AI サービスは起動しません。

2 つのフィクスチャによるゲート待機で、重なりを再現可能にしています。A と B の検証中に E と F をコミットし、続いて E と F の検証中に G と H のドラフトを開始します。 3 つすべてのデプロイで承認とデフォルトの再チェックが維持されます。最終リモートの新しいクローンでは、6 つのテストが成功します。

その後、G と H は編集内容を失わずにその結果へリフレッシュします。I と J もそこで開始します。この 4 つのドラフトは未提出のままです。エージェントまたはオペレーターが作業の作成、修正、リフレッシュ、再提出を行い、mergetrain がその作業をチェックして統合します。14 秒のアニメーションでは、この記録された時間帯を短縮したタイミングで繰り返します。

課題

ワークツリーを使うと、複数のエージェントが同じリポジトリをチェックアウト共有せずに編集できます。しかし、反映順を決定したり、統合後の結果をテストしたり、プッシュの競合を防いだり、ノート PC がプッシュの途中で停止した場合に何が起きたかを知らせたりはしません。

共有の統合ワークフローがなければ、オペレーターがブランチの順序を決め、ブランチ間の失敗を解決します。また、オペレーターがテストを再実行し、プッシュを管理します。こうした作業を繰り返すと、並行作業の速度が落ちることがあります。

mergetrain は、このワークフローを永続性のあるローカルキューに記録します。

agent branches → local queue → isolated integration worktree → combined gates
               → explicit approval → one atomic push → post-push verification

誰が使うべきですか？

次の場合は mergetrain をお使いください。

• 同じリポジトリで、複数のコーディングエージェントが一日を通してブランチを仕上げる場合。
• エージェントが Git worktree で作業し、デプロイ用 ref を push するのではなく、キューに登録する必要がある場合。
• 統合した結果を取り込む前に、ローカルテストに合格させる必要がある場合。
• 明示的に事前承認されたジョブのみを無人で処理したい場合。
• 複数のリポジトリにまたがるキューとランナーを、1 つのローカルハブで確認したい場合。

ハーネスに依存しません。Codex、Claude Code、agy、スクリプト、人間はすべて、同じ CLI と JSON コントラクトを使用します。

1 台のノート PC で Claude Code や Codex のセッションを複数実行していますか？1 台のノート PC 向けガイドでは、worktree、無人での取り込み、重いゲート、スリープと静穏時間、push ガード、結果レポートを取り上げています。各項目は使い捨てのリポジトリでテスト済みです。

誰が使うべきではありませんか？

次の場合は、おそらく mergetrain は必要ありません。

• 1 人または 1 つのエージェントが、一度に 1 つのブランチを取り込む場合。
• 変更はすべてすでに PR と、ホスティングサービス標準のマージキューを経由する場合。
• ホスト型のレビュー UI、組織全体の権限システム、またはリモートランナーサービスが必要な場合。
• 汎用のジョブキュー、CI プロバイダー、またはデプロイプラットフォームをお探しの場合。

PR を優先するチームには、GitHub Merge Queue または GitLab Merge Trains をお使いください。mergetrain はローカルエージェントと worktree を中心にした統合向けであり、PR の前、または PR と併用して使用します。

デフォルトはバッチ、必要に応じて順序処理

まずはデフォルトの batch をお使いください。 並列エージェントによる独立した作業に適しています。ランナーは開始時点でキューにある作業をまとめて処理します。すべてのエージェントが完了するまで待つことはありません。エージェントが失敗した送信を修正している間も、互換性のある作業を取り込めます。

各変更を個別に取り込む必要があり、失敗と再試行の後も元の送信順序を維持する必要がある場合は、ordered をお使いください。

比較	batch（デフォルト）	ordered（任意）
エージェント作業の例	A がログインを修正し、B が検索フィルターを追加し、C が管理画面を更新する	A、B、C がコンパイラーを最適化し、それぞれの変更を直前に取り込まれた結果と比較して測定する
取り込み単位	処理可能な送信をまとめて取り込む	一度に 1 件の送信
B が失敗した場合	B を切り離し、A+C のチェックに合格すれば、A+C を取り込める	A は取り込める。B が修正されて取り込まれるか、明示的にキャンセルされるまで、C は待機する
retry 後の B	キューの最後に加わる	元の位置を維持し、C より前に並ぶ

どちらのモードでも、エージェントは引き渡し後に次のタスクを開始できます。デプロイの承認と、デフォルトの push 前再チェックもどちらのモードでも維持されます。順序処理では各送信が個別に取り込まれるため、チェックの実行頻度が高くなる場合があります。キューの順序は送信時点で決まり、エージェントが作業を開始した時点では決まりません。また、コードの依存関係を表すものではありません。順序処理は Git への取り込みが成功した時点で終了します。push 後の検証に関する警告は、後続の作業を進めながらも表示されます。不確実な push が発生した場合は、引き続き調整が必要です。

利用可能なバージョン： ordered は 3.6.0 以降で利用できます。 通常の並列エージェント作業では、デフォルトの batch を維持してください。 エージェント作業の例、設定、アップグレード手順を参照してください。

適用範囲

リーストークンは、並行して動作する古い mergetrain ランナー をフェンスします。ただし、シェルアクセスと統合ブランチの認証情報を持つタスクエージェントによる任意の git push は遮断しません。「1 つのランナーが push を所有する」ことを、プロトコル上の前提ではなく強制される仕組みにするには、次のトポロジーを使用してください。

task agents: commit + exact-SHA enqueue; no integration push credential
runner:      separate deploy identity
remote:      protected integration branch; runner or reviewed PR path only

認証情報の分離とリモート保護がなければ、mergetrain は安全なトレインの組み立てと復旧のセマンティクスを提供しますが、参加者によるキューの迂回は防止できません。セキュリティの適用範囲を参照してください。

実際のデモを実行する

uvx mergetrain demo

このデモでは、使い捨てのリポジトリとローカルのベアリモートを作成し、実際の4つのブランチをエンキュー順にマージして、組み合わせた場合のみ発生するゲートの失敗、競合の原因特定、互換性のあるトレインのデプロイを実行します。後で結果を確認するには、--keep を使用します。各ステップを読んでから続行するには、--brief --pause を追加します。拡張ワークフローの録画では、修正、検証中にコミットされた作業、次のバッチ、3件の検証済みローカルデプロイも確認できます。

CLI の全録画

インストールと初回実行

# Install the machine-level CLI
uv tool install mergetrain          # or: pipx install mergetrain
# macOS: brew install yongjip/tap/mergetrain

# Codex: add the Git marketplace, then install the native skill + pinned MCP server
codex plugin marketplace add yongjip/mergetrain --ref main
codex plugin add mergetrain@mergetrain

# agy: install the native skill + pinned MCP server
agy plugin install https://github.com/yongjip/mergetrain

VS Code／GitHub Copilot または MCP の直接設定については、MCP のインストールとデプロイ確認ガイドを参照してください。

リポジトリを初期化します。

cd /path/to/your/repo
mergetrain init --project my-app --write

.mergetrain.yaml にプロジェクトゲートを1つ以上追加します。新しい設定では gates: [] となっているため、プロジェクトのテストは実行されません。pytest を使用する Python プロジェクトの場合：

gates:
  - name: tests
    run: python -B -m pytest -q -p no:cacheprovider

プロジェクトに適したテストコマンドを使用してください。ゲートの実行後、組み立てられたチェックアウトに変更が残っていてはいけません。init は AGENTS.mergetrain.md と CLAUDE.mergetrain.md も作成します。既存の AGENTS.md または CLAUDE.md からこれらのファイルにリンクしてください。タスク用ワークツリーを作成する前に、通常の統合手順を通じて設定と指示をコミットし、取り込みます。

タスクエージェントが自身のワークツリーでクリーンなブランチをコミットした後：

mergetrain status --json
mergetrain enqueue \
  --task "add health check" \
  --branch agent/health

タスクエージェントはエンキュー後に停止します。検証とデプロイが承認されたら、オペレーターのチェックアウトから次のコマンドを実行します。

mergetrain status
mergetrain deploy

時間のかかるゲートの場合は、早めに mergetrain validate を実行してください。このコマンドはプッシュを行わず、後で deploy を確認できるよう、正確に1つのトレインを Ready 状態にします。

deploy は設定済みのアトミックな Git ref 更新を指し、App Store、Kubernetes、その他のプロバイダーへのリリースを意味するものではありません。

エージェントはコミットしてエンキューします。1つのランナーが merge → test → push → verify を一貫して担当します。無人デーモンが処理するのは、人間が --auto を明示してエンキューしたジョブのみです。手動ジョブの場合、daemon --validate-only を使うとバックグラウンドでマージとゲートの実行ができますが、検証済みトレインの承認境界で一時停止し、プッシュは行いません。

設定、デーモン、複数リポジトリの Hub のセットアップについては、クイックスタートを参照してください。

Claude Code の並列セッションと Codex のワークツリーの統合

同じリポジトリ内で、Claude Code の並列セッションまたは Codex の並列ワークツリーからコミット済みブランチが作成される場合は、Git ワークツリーのマージキューを使用します。プラグインのインストールガイドを使って、どちらのクライアントもキューに接続できます。タスクエージェントはコミットしてエンキューした後、停止します。別途承認されたランナーがブランチを結合してテストし、プッシュを処理します。

Orca が管理するワークツリーについては、テスト済みのターミナルコマンド、共有キューの動作、検証、修復について、Orca のセットアップとキューのガイドを参照してください。Orca エージェントガイドでは、ネイティブ Codex、Claude Code、agy プラグインのセットアップと、範囲を限定したタスク／検証プロンプトを紹介しています。

worktree と git merge だけではだめなのですか？

worktree は並行編集を解決します。mergetrain は順序付けられた統合を解決します。

統合に関する懸念事項	worktree と手動マージ	mergetrain
取り込み順序	人またはエージェントがその都度決定	キューへの追加順を保持するキュー
統合後の検証	マージのたびに手動で再実行	組み立て済みのトレインそのものに対してゲートを実行
ブランチ間の失敗	手作業で原因を調査	分離実行で競合するペアを特定
プッシュの所有権	各セッションが ref を巡って競合する可能性がある	リースでフェンスされた単一のランナーがプッシュを所有
承認	シェルの慣例	検証／デプロイの意図を明示。--auto はオプトイン
クラッシュからの復旧	ローカルログから推測	SQLite の証拠とリモート ref を照合

エージェントはそれぞれ別の worktree を使います。単一の mergetrain ランナーが、それらのコミット済みの結果を統合します。

GitHub や GitLab のマージキューではだめなのですか？

関連する問題を解決しますが、対象とする運用モデルが異なります。

	Forge ネイティブのキュー	mergetrain
主な単位	プルリクエスト／マージリクエスト	コミット済みのローカルタスクブランチ
検証	Forge のマージグループとリモート CI	ローカルで組み立てたトレインとシェルゲート
レビュー	会話と承認の機能を内蔵	コードレビュー UI なし
インフラストラクチャ	Forge との連携とホスト型サービス	ローカル SQLite、Git worktree、任意の Git リモート
最適な用途	PR 主導のチームと分散レビュー	高スループットのローカルエージェント統合

これらのモデルは共存できます。検証済みのトレインをレビューブランチにプッシュして PR を 1 つ作成することも、議論が必要な変更には個別の PR を使うこともできます。 PR ワークフローガイド では、直接取り込み、PR 1 件、複数 PR、検証のみのパターンを説明しています。

中断された Git プッシュからの復旧

Git のプッシュが停止またはタイムアウトしても、リモートが更新を受け入れたかどうかは分かりません。mergetrain はデプロイの証拠を記録します。復旧手順では、再試行する前にリモート ref を確認します。まず mergetrain status --json を実行し、報告された復旧アクションとその承認要件に従ってください。復旧ガイドを参照してください。

コアとなる安全性の保証

• タスクの同一性を厳密に検証します。 承認時にタスクの HEAD と統合ベースを指定するため、ブランチが変更されたりベースが移動したりしても、承認が暗黙に再利用されることはありません。
• プッシュ前にすべてのゲートを通過します。 ブランチが成功しているだけでは不十分です。組み立てられたトレインが設定済みのゲートを通過しなければ、何も反映されません。
• フェンス制御された mergetrain の所有者は 1 つです。 SQLite のクレームとリーストークンによって、同じトレインを複数の mergetrain ランナーが同時に、または古い状態で変更することを防ぎます。リモート側での強制には、さらに前述の認証情報の構成が必要です。
• リモートをアトミックに更新します。 ペイロードの参照と永続的な refs/mergetrain/deploys/<sha> 復旧用参照は、同時に更新されます。
• リモートの状態に基づいて復旧します。 書き込み先行マーカーと固定されたコミットにより、reconcile は、停止されたプッシュが反映されたかどうかを判定できます。成功したデプロイを再実行したり、未完了のものを完了済みとして扱ったりすることはありません。
• 自動化は明示的に行います。 オプションなしの実行ではデプロイされません。デーモンが処理するのは、事前承認済みの --auto ジョブのうち、宛先とゲート／再利用／検証ポリシーが引き続き一致するものだけです。また、MCP によるデプロイには、引き続き人間による確認を帰属可能な形で行う必要があります。
• 状態を確認する入口は 1 つです。 status は内部の詳細を「待機中」「実行中」「準備完了」「要対応」「完了」に整理し、次に実行できる安全なコマンドを返します。inspect は必要な場合に限り、ジョブレベルの根拠を提示します。

キューの状態、ロック、トレインの組み立て、ゲートはローカルに保持されます。設定済みの Git リモートとプッシュ後の検証では、外部サービスが引き続き使用される場合があります。ゲートと検証のコマンドは信頼されたコードです。無人ジョブを有効にする前に、セキュリティ境界を確認してください。

これらの保証は、Python 3.10～3.14 を使用した macOS と Linux、および Windows で、git push --atomic 周辺への実際の Git 障害注入を含めて検証されています。専用の負荷試験用リポジトリでは、計画的な競合の復旧と、リモートの状態と判定が一致した実際のプッシュ停止後の照合を含め、20 件のトレインすべてが反映されました。詳細は負荷試験の証拠を参照してください。その後、mergetrain stats --json を使って、独自のキューの証拠を確認できます。

詳しく見る

• はじめに：クイックスタート · インストール · CLI · 設定
• 理解する：設計とアーキテクチャ · マシンコントラクト · PR ワークフローの比較
• 運用する：効率的な運用 · 障害モードと復旧 · アップグレード · デーモン · マルチリポジトリ Hub
• 信頼性と拡張：セキュリティ · エージェントコントラクト · エージェント導入ベンチマーク · 製品名を使わない発見ベンチマーク · ローカルマルチエージェントベンチマーク · MCP サーバー · アダプターパターン · 製品の範囲

安定したインターフェース

通常の CLI は、意図的に 6 つの動詞に限定されています。

init  status  enqueue  validate  deploy  inspect

バージョン 3 は、長期にわたって維持される製品文法です。v4 の予定はありません。新しい機能はこれらの動詞に収めるか、高度なオペレーター向けのインターフェースにとどめる必要があります。また、v3 の JSON および MCP コントラクトは、 互換性ポリシーに記載されたコントラクトのバージョン更新を除き、後方互換性を保ちながら拡張されます。

最新の公開リリースは、上記の PyPI バッジに表示されています。 問題や運用レポートは、 GitHubでお寄せください。

ライセンス

MIT ライセンスの下で公開されています。