Foremerge is the open-source coordination protocol for coding agents, built above Git. Claude Code in one worktree, Codex in another: agents from any provider share intent, semantic claims, dependencies, provisional ChangeSets, decisions, and verification through one store, so plans collide in a queryable database, not in your merge.
# Agent A announces its plan $ foremerge --json intent publish --agent "$STRIPE_AGENT" \ --task modernize-payments \ --summary "Replace PaymentService with StripePaymentService" \ --scope symbol:PaymentService=replace # Agent B announces a plan of its own $ foremerge --json intent publish --agent "$PAYPAL_AGENT" \ --task add-paypal \ --summary "Add PayPal support to PaymentService" \ --scope symbol:PaymentService=extend | jq '.data.conflicts[0]' { "kind": "destructive_vs_additive", "severity": "HIGH", "explanation": "One intent will replace `PaymentService` while the other will extend it; both declare the same semantic scope.", "suggestion": "Coordinate on a stable `PaymentProvider` contract first, then implement StripePaymentProvider and PayPalPaymentProvider behind it and migrate callers deliberately. This is a heuristic suggestion, not an automatic design decision." }
How it works
Say you have two AI agents working on the same project at the same time. Each one gets its own copy of the code, so they never fight over files. Both finish. Both look correct. Then you find they undid each other's work.
Git cannot warn you about that, because Git compares text and not intent. It will stop you when two agents edit the same part of the same file. What it cannot see is two edits that are each perfectly reasonable on their own and land in different files. If one agent moves every caller onto a new StripePaymentService while another adds PayPal support to the old PaymentService, nothing overlaps, so Git merges both without complaint and the PayPal work is left stranded on a class nothing calls any more.
Not the code, just the target, like "I am going to change the sendEmail function."
It is a small database inside your project's .git folder, so every agent on your machine sees the same picture, whether it is Claude, Codex, or Cursor.
Foremerge names the two agents, explains why their plans clash, and suggests how to split the work. Both worktrees are still clean at that point, so no work has to be thrown away.
Think of it as a shared whiteboard. Before an agent starts, it writes down what it is about to work on, and it reads what everyone else already wrote.
Two things Foremerge deliberately does not do. It never locks a file or blocks an agent, because a single crashed agent would then stall the whole fleet, so the warnings are advisory and you stay in charge. And it never asks a model to judge conflicts, so the same inputs always produce the same answer.
The problem
One agent removes the extension point the other depends on. No overlapping lines, no diff, nothing for Git to flag until both implementations exist and the rework is expensive. Foremerge compares declared scopes and intent language before implementation and raises an explainable, advisory finding. No hard locks, no LLM in the detection path.
Quickstart
Foremerge is one binary. The fastest path is to let the agent you already use do the install and wire itself in, then follow the protocol from that point on.
Run it from inside the repository you want to coordinate. Change the check in step 4 to whatever this repository's real test command is.
A checksum-verified binary for macOS and Linux, or from crates.io if you have Rust. Windows binaries are on the releases page.
setup all installs the skill and MCP entry for Claude Code, Codex, and Cursor. Your client will ask before enabling anything.
Two agents can now publish conflicting intents and see the finding above before either writes a line. Full documentation is in the docs directory.
How it fits
Every agent keeps its own isolated worktree. Coordination state lives in one SQLite database under the repository's Git common directory, so linked worktrees share it automatically. Mutations update typed projections, materialize graph edges, and append a hash-chained semantic event in a single transaction.
Register agents, publish intents, claim scopes, query who is changing what, and gate ChangeSets, with --json for scripting.
publish_intent, claim_work, check_conflicts, publish_changeset, run_verification, accept_changeset and twelve more, all over stdio. No daemon required.
An authenticated local HTTP API with an OpenAPI schema, for harnesses that prefer HTTP to stdio.
Grey while it is only declared, amber while the evidence is self-reported, green once Foremerge itself ran the check, and a receipt once Git owns it. Agent-reported test results are provenance, never proof. Acceptance requires Foremerge-executed validation against the exact Git fingerprint of the candidate, and any change after validation makes that evidence stale.
Mixed fleets
The protocol carries nothing provider-specific, so heterogeneous fleets are the design center, not an edge case. Any MCP-capable client drives the same tools; anything else uses the CLI or JSON API. Every ChangeSet records which agent and which model did what, validated how, against which exact Git fingerprint. A mixed Claude + Codex run doesn't just work: it produces the cross-model coordination data nobody else is collecting.
Semantic scopes
File paths miss API, schema, configuration, infrastructure, and cross-language collisions. Foremerge scopes name the thing that is actually contended:
Claims are leased and advisory: overlap produces a warning and shared context, never a lock. Twelve scope kinds ship in 0.1.0.
What it does not claim
The full trust model is in docs/limitations.md. Protocol feedback on scope vocabulary, conflict evidence, and verification policy is the contribution we want most: start a discussion.
