Foremerge

Foremerge は、Git の上に構築された、コーディングエージェント向けのオープンソースの連携プロトコルです。エージェントは分離したワークツリーを維持しながら、意図、セマンティッククレーム、依存関係、暫定的な ChangeSet、決定、検証、来歴（provenance）を共有します。

ステータス: Foremerge 0.4.0 は pre-1.0 のローカルファースト MVP です。CLI、JSON API、MCP サーバー、SQLite ストア、決定的な衝突検出器、検証ゲート付きライフサイクルは実装済みです。公開スキーマは今後も変更される可能性があります。複数マシンでの共有モードと、公開されたベンチマーク結果はまだ存在しません。

仕組み

同じプロジェクトで2つの AI エージェントが同時に作業しているとします。それぞれがコードの自分のコピーを持つため、ファイルをめぐって争うことはありません。両方とも完了し、両方とも正しく見えます。それなのに、お互いの作業を打ち消し合っていたことが判明します。

Git はテキストを比較するのであって意図を比較するのではないため、Git はそれを警告できません。2つのエージェントが同じファイルの同じ部分を編集したときは、Git が止めてくれます。しかし、それぞれ単独では完全に合理的で、しかも別々のファイルに収まる2つの編集は見えません。あるエージェントがすべての呼び出し元を新しい StripePaymentService に移行し、別のエージェントが古い PaymentService に PayPal サポートを追加した場合、重なる部分はないため、Git は何も言わずに両方をマージし、PayPal の作業は誰も呼ばなくなったクラスに取り残されます。

Foremerge は、エージェントが作業を行う前に、これから行おうとしていることを宣言させることでこれを解決します。

1. 各エージェントは、これから触ろうとしている対象を宣言します。 コードではなく、対象だけです。「sendEmail 関数を変更します」のように。

2. すべてのエージェントは1つの共有リストを読み取ります。 それはプロジェクトの .git フォルダ内にある小さなデータベースで、Claude でも Codex でも Cursor でも、あなたのマシン上のすべてのエージェントが同じ状況を把握できます。

3. 2つの計画が衝突したら、すぐに知らせてくれます。 Foremerge は2つのエージェントを特定し、なぜ計画が衝突するのかを説明し、作業をどう分割するかを提案します。その時点では両方のワークツリーはまだクリーンなので、破棄しなければならない作業はありません。

共有ホワイトボードのようなものだと考えてください。エージェントは開始する前に、これから取り組むことを書き込み、他の全員がすでに書いたことを読み取ります。

Foremerge があえて行わないことが2つあります。ファイルをロックしたりエージェントをブロックしたりは決してしません。1つのエージェントがクラッシュしただけでエージェント群全体が停止してしまうからです。したがって、警告は助言であり、主導権はあなたにあります。また、モデルに衝突を判断させたりもしません。同じ入力には常に同じ答えが返るからです。

Related MCP server: batuta-mcp

Git にはまだ見えない衝突

Agent A: Replace PaymentService with StripePaymentService
Agent B: Add PayPal support to PaymentService

これらのエージェントは、同じ行に触れることなく別々のツリーで作業できます。それでも計画は衝突します。一方は拡張ポイントを削除し、もう一方はそれに依存しているからです。

両方のエージェントが同じ symbol:PaymentService スコープを宣言し、一方はそれを replace すると、もう一方は extend すると宣言します。Foremerge は、どちらかがコードを書く前にこれら2つの宣言を比較し、HIGH のアドバイザリを発行して、PaymentProvider のような安定した抽象化で協調することを提案します。その提案は説明可能な根拠であり、自動的なアーキテクチャ決定やハードロックではありません。

操作はサマリーから読み取るのではなく宣言されるため、各エージェントが計画をどのように表現したかは関係ありません。「Consolidate payments onto Stripe」も「Replace PaymentService with Stripe」も同じ結論に達します。

Git は永続的なリポジトリのままです。Foremerge は、その上に欠けていた共有認識を提供します。

実際に 0.1.0 のリリースバイナリを examples/terminal-session.txt で実行して取得した実際の衝突フィールドからレンダリングしています。表示されているコマンドは、示されている jq フィルタを使用しています。出力は読みやすさのために省略されています。

クイックスタート: 5分以内で最初の衝突を確認する

コーディングエージェントにやってもらう

連携させたいリポジトリの中で、これを Claude Code、Codex、または Cursor に貼り付けてください:

Set up Foremerge in this repository so we can coordinate parallel agents.

1. Install it:      curl -fsSL https://foremerge.com/install.sh | sh
2. Initialize:      foremerge init
3. Wire this client and any others in use: foremerge setup all
4. Register the check I should be validated against, for example:
                    foremerge checks set test -- cargo test --all-targets
5. Confirm:         foremerge doctor --client all

Then read the Foremerge skill that step 3 installed for this client and follow
it from now on: publish your intent with semantic scopes before editing, claim
the scope, and check for conflicts before you start.

ステップ4は、このリポジトリの実際のテストコマンドに合わせて調整してください。ステップ3ではクライアントに MCP サーバーの有効化を求めるため、実行前にプロンプトが表示されます。Codex の登録はユーザーレベルですが、1回の登録ですべてのリポジトリで機能します。連携させたいリポジトリの中で Codex を起動してください。

あるいは自分でやる

最近の Git と jq が必要です。チェックサム検証済みのプレビルドリリースバイナリをインストールしてください（macOS と Linux 対応。スクリプトは ~/.local/bin にインストールします）:

curl -fsSL https://foremerge.com/install.sh | sh

[!TIP] 2つのコマンド、1つのプログラム。 これにより foremerge と fmg がインストールされます。fmg は同じバイナリの短い名前です。fmg status と foremerge status は同じことを行います。以下の例では foremerge と表記していますが、どちらでもお好みで入力してください。

または、Rust 1.85+ でソースからビルドします: cargo install --locked --git https://github.com/naw103/foremerge foremerge、あるいはチェックアウトから cargo install --locked --path . を実行します。Windows バイナリはリリースページにあります。更新するにはインストーラを再実行してください。次に、連携させたいリポジトリの中で:

foremerge init
foremerge doctor

インストーラ、リリースアーカイブ、cargo install はすべて、0.4.0 以降では両方の名前を提供します。PATH 上に fmg という名前で応答する別のプログラムがすでにある場合、インストーラはそれを上書きせず、そのままにしてその旨を伝えます。

このリポジトリで使用するクライアント向けにネイティブスキルと MCP エントリをインストールし、エージェントが名前で要求できる信頼済みチェックを定義します:

foremerge setup all
foremerge checks set test -- cargo test --all-targets
foremerge doctor --client all

受理は検証ゲートで制御されます。Foremerge はエージェントの言葉をそのまま信じるのではなく、チェック自体を実行します。フル CI スイートではなく、ビルドや型チェックなど、高速で壊れた引き継ぎを実際に検出できるチェックを選んでください。このゲートは、他のエージェントがその作業を完了として扱ってよいかを決定するものであり、CI の代わりにはなりません。このリポジトリに検証すべき意味のあるものが何もない場合は、常に成功するチェックを登録するのではなく、一度だけその旨を伝えてください:

foremerge checks policy advisory

そのように受理された作業は、理由とともに UNVERIFIED として記録されるため、監査証跡が、実際には実行されていないチェックを実行済みとして示すことは決してありません。foremerge doctor は、登録されたチェックがここで実際に実行できるかどうかを報告します。これはエージェントのワークツリーでは重要です。依存関係ディレクトリは通常 gitignore されており、git worktree add はそれらを作成しないからです。

1つのクライアントに対しては、setup codex、setup claude、または setup cursor を使用します。セットアップは無関係な設定（プロジェクトの MCP JSON のキー順序を含む）を保持します。Foremerge をアップグレードすると、編集されていない Foremerge 自身のスキルファイルはその場で更新されますが、あなたが編集したスキルファイルや、異なる Foremerge MCP エントリは、明示的に --force を渡さない限り置き換えられることはありません。setup all はすべてのクライアントを試行して各結果を報告し、いずれかが失敗した場合は非ゼロで終了します。Codex の MCP 登録はユーザーレベルで、すべてのリポジトリに適用され、Codex を起動したディレクトリから解決されます。エージェントクライアントのセットアップ を参照してください。

init は、リポジトリの Git 共通ディレクトリ配下にローカルの連携状態を作成します。追跡されたファイルは変更されません。以下のワークツリーなしのセッションでも、コード作成前の検出を試すには十分です。実際のコーディングエージェントは、分離したワークツリーと実際のモデル識別子を登録する必要があります。

STRIPE_AGENT=$(
  foremerge --json agent register \
    --name stripe-agent \
    --no-worktree |
  jq -er '.data.id'
)

STRIPE_RESULT=$(
  foremerge --json intent publish \
    --agent "$STRIPE_AGENT" \
    --task "modernize-payments" \
    --summary "Replace PaymentService with StripePaymentService" \
    --scope symbol:PaymentService=replace
)
STRIPE_INTENT=$(printf '%s\n' "$STRIPE_RESULT" | jq -er '.data.intent.id')

PAYPAL_AGENT=$(
  foremerge --json agent register \
    --name paypal-agent \
    --no-worktree |
  jq -er '.data.id'
)

PAYPAL_RESULT=$(
  foremerge --json intent publish \
    --agent "$PAYPAL_AGENT" \
    --task "add-paypal" \
    --summary "Add PayPal support to PaymentService" \
    --scope symbol:PaymentService=extend
)
PAYPAL_INTENT=$(printf '%s\n' "$PAYPAL_RESULT" | jq -er '.data.intent.id')

printf '%s\n' "$PAYPAL_RESULT" |
  jq '.data.conflicts[] | {kind, severity, scope, explanation, suggestion}'

printf '%s\n' "$PAYPAL_RESULT" |
  jq '.data.related_work[] | {agent, summary, asserted, overlap}'

最初のコマンドは、ローカルでの実行によるライブの検出結果を出力します。2番目のコマンドは related_work、つまりもう一方のエージェントの意図と、両方の宣言された操作で重なるすべてのスコープを出力します。Foremerge は何が重なるかを示します。その意味を判断するのはあなたであり、foremerge assess record でそれを記録します。先にファイルを変更する必要はありません。キャプチャされた明確にラベル付けされたトランスクリプトを examples/terminal-session.txt で確認できます。

クレームは、どちらのエージェントもブロックせずに所有権のコンテキストを追加します:

foremerge --json work claim \
  --agent "$STRIPE_AGENT" \
  --intent "$STRIPE_INTENT" \
  --scope symbol:PaymentService \
  --reason "Changing the provider boundary" >/dev/null

foremerge --json work claim \
  --agent "$PAYPAL_AGENT" \
  --intent "$PAYPAL_INTENT" \
  --scope symbol:PaymentService \
  --reason "Adding another provider" |
  jq '.data | {advisory_only, warnings}'

foremerge --json work query --scope symbol:PaymentService |
  jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'

両方のクレームは成功します。2番目のレスポンスには重複警告が含まれます。クレームは貸与されたアドバイザリであり、排他的な所有権ではないためです。

Git の上でどう機能するか

  coding agent A                                  coding agent B
        |                                               |
  isolated worktree A                            isolated worktree B
        |                                               |
        +--------- semantic events, not edits ----------+
                              |
                    CLI / MCP / JSON API
                              |
                     Foremerge service
                    /        |        \
       SQLite coordination   git CLI   validation argv
       in <git-common-dir>       |           |
                    \         Git repository /
                     durable commits and refs

すべてのフロントエンドは同じサービスとストアを使用します。セマンティックグラフは次のとおりです:

Agent → Task → Intent → Claim → Symbol → Dependency
      → ChangeSet → Test → Result → Decision → Provenance

ミューテーションは、型付き SQLite プロジェクションを更新し、グラフのエッジを具体化し、ハッシュチェーンされたセマンティックイベントを1つのトランザクションで追加します。このログは改ざんの証拠として有用ですが、リモートのアイデンティティ署名や分散合意ではありません。

Git ワークツリー: 隔離されたファイル、共有される認識

Foremerge は Git 共通ディレクトリを解決し、デフォルトのデータベースを次の場所に保存します:

<git-common-dir>/foremerge/state.sqlite3

リンクされたワークツリーは、チェックアウトされたファイルが別々であっても、その共通ディレクトリを共有します。標準 Git に対する Foremerge の薄いラッパーでワークツリーを作成します:

foremerge worktree create \
  --branch agent/paypal \
  --path ../payments-paypal \
  --base HEAD

foremerge --cwd ../payments-paypal --json agent register \
  --name paypal-agent \
  --model "$ACTUAL_MODEL_ID"

同じリポジトリ内の別のワークツリーは、登録されたエージェントとその意図をすぐに認識します。--database PATH または FOREMERGE_DB でストレージを上書きできますが、状態を共有するには、ローカルのすべてのエージェントが同じデータベースを指す必要があります。MVP は SQLite をマシン間で複製しません。ネットワークマウントされたデータベースから分散安全性を推定しないでください。

Foremerge は ChangeSet フィンガープリントと受け入れ済み refs のために Git の状態をスナップショットします。自動的に merge、rebase、cherry-pick、push を行ったり、ターゲットブランチを更新したりはしません。

セマンティックワークフロー

INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL
       ─validate current fingerprint→ VALIDATED
       ─accept gates→ ACCEPTED ─record Git ref→ COMMITTED

サポートされているスコープの種類は次のとおりです:

symbol api schema config infra test migration env file component contract domain

最も狭くて有用なセマンティックスコープを公開してください。ファイルパスだけでは、API、設定、スキーマ、インフラストラクチャ、言語をまたぐ衝突を見逃します。

よく使うコマンド:

foremerge <command> --help を実行すると、現在のすべてのフラグが表示されます。--json、--cwd、--database などのグローバルフラグは、サブコマンドの前後に指定できます。

ChangeSet と検証ゲート

ChangeSet には、エージェント/モデル、タスクとインテント、影響を受けるファイル/シンボル/コントラクト、依存関係、実装サマリー、報告されたテスト、決定、来歴、ワークツリー、フィンガープリント、ステータス、Git 参照が記録されます。受理された候補と、その後のランディングコミットは、それぞれ accepted_commit と integration_commit として別々に保持されます。

誠実な統合の順序は次のとおりです。

1. インテントを公開し、セマンティックスコープを主張し、実装を進行中としてマークします。

2. 分離されたエージェントブランチ上で作業し、コミットします。

3. そのクリーンな候補に対する ChangeSet を公開します。

4. Foremerge に、その正確なフィンガープリントに対する検証の実行を依頼します。

5. 高優先度の競合を解決し、その後、依然としてクリーンで検証済みの参照を受理します。

6. 通常の Git またはプルリクエストで統合します。

7. 永続的な統合コミットを Foremerge に記録します。

foremerge work claim \
  --agent "$AGENT_ID" \
  --intent "$INTENT_ID" \
  --scope component:payments
foremerge work start "$INTENT_ID" --agent "$AGENT_ID"

# Implement the change and commit it on this isolated branch before publishing.
CHANGESET_ID=$(
  foremerge --json changeset publish \
    --agent "$AGENT_ID" \
    --intent "$INTENT_ID" \
    --summary "Introduce PaymentProvider and StripePaymentProvider" \
    --file src/payments.rs \
    --symbol PaymentProvider \
    --symbol StripePaymentProvider \
    --contract payment-provider \
    --provenance-json '{"source":"coding-agent"}' \
    --git-ref HEAD \
    --worktree "$PWD" |
  jq -er '.data.id'
)

foremerge changeset validate "$CHANGESET_ID" \
  --worktree "$PWD" \
  -- cargo test --all-targets

foremerge changeset accept "$CHANGESET_ID" --git-ref HEAD

# Integrate with ordinary Git, then record the commit that actually landed.
foremerge changeset commit "$CHANGESET_ID" --git-ref main

エージェントが報告する --reported-test COMMAND=STATUS の値は来歴にすぎません。それらは受理条件を満たしません。Foremerge が所有する検証では、コマンドの引数ベクトル、終了ステータス、出力、所要時間、候補のフィンガープリントが記録されます。検証後に変更が検出された場合、その試行は非権威となりますが、その出力と変更パス診断は changeset attempts で照会可能なままです。

使い捨ての未追跡出力を生成する信頼済みチェックの場合、オペレーターは追跡ファイルを変更せずに、完全一致またはディレクトリプレフィックスのルールを設定できます。

foremerge validation-exclusions set \
  --path coverage.log \
  --path target/validation-reports/

正規化されたポリシーダイジェストは候補フィンガープリントの一部であり、追跡済みの変更は決して除外できず、MCP はポリシーを変更できず、生成されたファイルは受理前に削除する必要があります。ADR 0001 を参照してください。

受理には、クリーンなワークツリーと未解決の HIGH 競合がないことも必要です。ただし、呼び出し元が明示的な --allow-high-conflicts オーバーライドを --override-reason "..." とともに意図的に使用する場合を除きます。競合は明示的な理由を添えて解決することを推奨します。受理により refs/foremerge/accepted/<changeset-id> が作成されます。コードのマージは行われません。

検証コマンドは、オペレーティングシステムの権限を持つ信頼済みローカルコードとして実行されます。Foremerge はそれらをサンドボックス化しません。

エージェントクライアントと MCP: 完全なライフサイクルツール

foremerge mcp を stdio 上で実行します。MCP は HTTP デーモンを必要としません。両者は同じデータベース上のアダプターです。

有効な最小構成である examples/mcp-config.json から始めてください。この構成は、クライアントがリポジトリを作業ディレクトリとして foremerge を起動することを想定しています。リポジトリの作業ディレクトリ設定がないクライアントは、mcp の前に絶対パスの --database を渡す必要があります。リンクされたワークツリーの .git がディレクトリであると想定するのではなく、Git 共通ディレクトリを導出してください。

インストーラー、ネイティブスキルの場所、クライアント固有の MCP ファイル、診断、安全な置換ルールについては、エージェントクライアントのセットアップ を参照してください。トランスポートの動作、スキーマ、名前付きチェック、入力例、マルチワークツリー構成については、MCP セットアップ を参照してください。

ソースクローンには、.codex/skills、.claude/skills、.cursor/skills に同等のスキルと、ポータブルな Claude および Cursor 用 MCP テンプレートが含まれています。Cargo インストールには標準スキルが埋め込まれているため、foremerge setup はこのソースツリーをコピーしなくても別のリポジトリにインストールできます。

ローカル JSON API

デーモンはデフォルトで、http://127.0.0.1:47811 上の認証付きループバック HTTP を使用します。init は、プラットフォームがサポートする場合、プライベートファイル権限でベアラートークンを作成します。

一方のターミナルで:

foremerge daemon

もう一方のターミナルでは、トークンパスを推測するのではなく、Foremerge から読み取ってください:

export FOREMERGE_URL=http://127.0.0.1:47811
TOKEN_FILE=$(foremerge --json init | jq -er '.data.token_file')
FOREMERGE_TOKEN=$(tr -d '\r\n' < "$TOKEN_FILE")

curl --fail --silent --show-error \
  --header "Authorization: Bearer $FOREMERGE_TOKEN" \
  --get "$FOREMERGE_URL/v1/work" \
  --data-urlencode 'scope=symbol:PaymentService' |
  jq .

トークンを出力、コミット、共有しないでください。/healthz はデータベースを使用しないプロセスの生存確認であり、/readyz は制限付きで待機しないストアプローブです。どちらも公開されています。ページングされたイベントチェーン監査を含むすべての /v1 ルートは、信頼できるローカルテスト用にデーモンが意図的に --no-auth で起動された場合を除き、トークンを必要とします。MVP は非ループバックバインドを拒否し、堅牢化された公開デプロイメントのセキュリティモデルではありません。

CLI のエスケープハッチである foremerge request は、ローカル認証を自動的に読み取ります。実行可能な curl ウォークスルーは examples/api-requests.sh にあります。完全なルートとエラーのリファレンスは JSON API です。

MVP が意図的に主張しないこと

• 競合検出は決定的で説明可能ですが、ヒューリスティックです。同義の概念を見逃したり、互換性のある作業に対して警告したりすることがあります。

• クレームは警告を行うだけです。ファイル、シンボル、エージェントをロックすることは決してありません。

• 検証の合格が証明するのは、記録されたコマンドが記録されたフィンガープリントに対して合格したことだけであり、テスト計画が完全だったことではありません。

• Git 参照とプロセス結果は、自己申告のモデル、プロンプト、テストの記述よりも強い証拠です。

• イベントチェーンは保持されたチェーン内の変更を検出します。署名、リモート構成証明、外部チェックポイントではありません。

• ローカル SQLite は共有モードの合意ではなく、ループバックのベアラートークンは公開デプロイメントのセキュリティモデルではありません。

• 実行可能なベンチマークフィクスチャ、再現可能なクエリハーネス、ベンチマーク計画はありますが、調整ありと調整なしのパフォーマンス結果の公開はまだありません。

• Foremerge は、コードレビュー、アーキテクチャのオーナーシップ、CI、セキュリティスキャン、Git ホスティングのルール、バックアップを置き換えるものではありません。

Foremerge を統合ゲートとして使用する前に、完全な制限事項と信頼モデルをお読みください。

ドキュメント

また、変更履歴、セキュリティポリシー、行動規範 も参照してください。

コントリビューションとライセンス

コントリビューション、特にスコープの語彙、競合の証拠、ChangeSet の来歴、検証ポリシーに関するプロトコルフィードバックを歓迎します。CONTRIBUTING.md を読んでから、完全なローカルゲートを実行してください：

make verify

Foremerge は Apache License 2.0 の下でライセンスされています。