Foremerge

Foremerge

Foremerge is the open-source coordination protocol for coding agents, built above Git. Agents keep isolated worktrees while sharing intent, semantic claims, dependencies, provisional ChangeSets, decisions, validation, and provenance.

Status: Foremerge 0.6.0 is a pre-1.0, local-first MVP. The CLI, JSON API,

MCP server, SQLite store, deterministic conflict detector, and

verification-gated lifecycle are implemented. Public schemas may still

change. Published benchmark results do not yet exist, and coordination

between machines is outside this project's scope.

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.

Foremerge fixes this by having agents announce what they are about to do, before they do it.

1. Each agent says what it is about to touch. Not the code, just the target, like "I am going to change the sendEmail function."
2. Every agent reads from one shared list. 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.
3. If two plans collide, you hear about it right away. 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 conflict Git cannot see yet

Agent A: Replace PaymentService with StripePaymentService

Agent B: Add PayPal support to PaymentService

These agents can work in different trees without touching the same line. The plans still collide: one removes the extension point while the other depends on it.

Both agents declare the same symbol:PaymentService scope, one saying it will replace it and the other that it will extend it. Foremerge compares those two declarations before either writes code, raises a HIGH advisory, and suggests coordinating on a stable abstraction such as PaymentProvider. That suggestion is explainable evidence, not an automatic architecture decision or a hard lock.

Because the operation is declared rather than read out of the summary, it does not matter how either agent phrased its plan. "Consolidate payments onto Stripe" and "Replace PaymentService with Stripe" reach the same verdict.

Git remains the durable repository. Foremerge supplies the missing shared awareness above it.

_Rendered from the actual conflict fields captured by the 0.1.0 release-binary run in examples/terminal-session.txt. The displayed command uses the shown jq filter; output is abridged for readability._

Quickstart: first conflict in under five minutes

Let your coding agent do it

Paste this into Claude Code, Codex, or Cursor from inside the repository you want to coordinate:

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.

Adjust step 4 to whatever this repository's real test command is. Step 3 asks the client to enable an MCP server, so it will prompt you before doing so. The Codex registration is user level, but one registration serves every repository: start Codex inside the repository you want it to coordinate.

Or do it yourself

You need a recent Git and jq. Install a prebuilt, checksum-verified release binary (macOS and Linux; the script installs to ~/.local/bin):

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

[!TIP]

Two commands, one program. This installs foremerge and fmg, the same

binary under a shorter name, so fmg status and foremerge status do the

same thing. Examples below spell out foremerge; type whichever you prefer.

Or install from npm (macOS, Linux with glibc, Windows x64). The package carries the same release binaries, so nothing is compiled or downloaded at install time:

npm install -g foremerge

Or build from source with Rust 1.85+: cargo install --locked --git https://github.com/naw103/foremerge foremerge, or cargo install --locked --path . from a checkout. Windows binaries are on the releases page. To update, upgrade the same way you installed, then re-run foremerge setup and restart your agent clients; Upgrading Foremerge explains why each step matters. Then, inside the repository you want to coordinate:

foremerge init

foremerge doctor

The installer, the release archives and cargo install all carry both names from 0.4.0 onward. If something else on your PATH already answers to fmg, the installer leaves it alone and says so rather than shadowing it.

Install the native skill and MCP entry for any clients used in this repository, then define the trusted checks agents may request by name:

foremerge setup all

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

Acceptance is verification-gated: Foremerge runs the check itself rather than taking an agent's word for it. Pick a check that is fast and that would actually catch a broken handoff, such as a build or a typecheck, rather than a full CI suite; this gate decides whether other agents may treat the work as done, and it does not replace CI. If this repository has nothing meaningful to verify, say so once rather than registering a check that always passes:

foremerge checks policy advisory

Work accepted that way is recorded as UNVERIFIED with the reason, so the audit trail never implies a check ran when none did. foremerge doctor reports whether the registered checks can actually run here, which matters in agent worktrees, because dependency directories are usually gitignored and git worktree add will not create them.

Use setup codex, setup claude, or setup cursor for one client. Setup preserves unrelated configuration (including key order in project MCP JSON). Upgrading Foremerge refreshes its own unedited skill file in place, but a skill file you edited, or a differing Foremerge MCP entry, is never replaced unless you explicitly pass --force. setup all attempts every client and reports each result, exiting nonzero if any failed. The Codex MCP registration is user-level and serves every repository, resolved from the directory Codex is started in; see agent client setup.

init creates local coordination state under the repository's Git common directory. It does not change tracked files. The following no-worktree sessions are enough to exercise pre-code detection; real coding agents should register their isolated worktrees and actual model identifiers.

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}'

The first command prints the live finding from your local run. The second prints related_work: the other agent's intent and every overlapping scope with both declared operations. Foremerge states what overlaps; you decide what it means and record that with foremerge assess record. No files need to change first. Inspect the captured, clearly labeled transcript in examples/terminal-session.txt.

Claims add ownership context without blocking either agent:

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}'

Both claims succeed. The second response includes an overlap warning because a claim is a leased advisory, never exclusive ownership.

_Recorded against the released 0.4.0 binary; every command and its output is real._

How it fits above Git

  coding agent A