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" \ --summary "Replace PaymentService with StripePaymentService" \ --scope symbol:PaymentService # Agent B announces a plan of its own $ foremerge --json intent publish --agent "$PAYPAL_AGENT" \ --summary "Add PayPal support to PaymentService" \ --scope symbol:PaymentService { "kind": "replace_vs_extend", "severity": "HIGH", "explanation": "One intent will replace `PaymentService` while the other will extend it; both rely on exact semantic scope.", "suggestion": "Coordinate on a stable `PaymentProvider` contract first, then implement StripePaymentProvider and PayPalPaymentProvider behind it and migrate callers deliberately." }
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.
register_agent, publish_intent, claim_work, query_work, check_conflicts, publish_changeset, coordinate_with_agent, all over stdio. No daemon required.
An authenticated local HTTP API with an OpenAPI schema, for harnesses that prefer HTTP to stdio.
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 seven 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.