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.
| Tell your agent to install |
→ |
Done |
→ |
See collisions before they land |
| Paste one line into Claude Code, Codex, or Cursor |
|
It installs Foremerge and wires itself up |
|
Every agent sees what the others are about to change, even in separate worktrees |
Status: Foremerge 0.4.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. Shared multi-machine mode and published benchmark results do not yet
exist.
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.
- Each agent says what it is about to touch. Not the code, just the
target, like "I am going to change the
sendEmail function."
- 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.
- 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 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,
re-run the installer. 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 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
Every frontend uses the same service and store. The semantic graph is:
Agent → Task → Intent → Claim → Symbol → Dependency
→ ChangeSet → Test → Result → Decision → Provenance
Mutations update typed SQLite projections, materialize graph edges, and append a
hash-chained semantic event in one transaction. The log is useful tamper
evidence; it is not a remote identity signature or distributed consensus.
Git worktrees: isolated files, shared awareness
Foremerge resolves the Git common directory and stores its default database at:
<git-common-dir>/foremerge/state.sqlite3
Linked worktrees share that common directory even though their checked-out
files are separate. Create a worktree with Foremerge's thin wrapper around
stock Git:
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"
Another worktree in the same repository sees the registered agent and its
intents immediately. You can override storage with --database PATH or
FOREMERGE_DB, but every local agent must point at the same database to share
state. The MVP does not replicate SQLite across machines; do not infer
distributed safety from a network-mounted database.
Foremerge snapshots Git state for ChangeSet fingerprints and accepted refs. It
does not automatically merge, rebase, cherry-pick, push, or update a target
branch.
Semantic workflow
INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL
─validate current fingerprint→ VALIDATED
─accept gates→ ACCEPTED ─record Git ref→ COMMITTED
Supported scope kinds are:
symbol api schema config infra test migration env file component contract domain
Publish the narrowest useful semantic scope. File paths alone miss API,
configuration, schema, infrastructure, and cross-language collisions.
Common commands:
| Boundary |
Command |
| Register provenance |
foremerge agent register --name NAME --model MODEL |
| Publish intent |
foremerge intent publish --agent ID --task TASK --summary TEXT --scope KIND:KEY=OPERATION |
| Claim scope |
foremerge work claim --agent ID --intent ID --scope KIND:KEY |
| Start implementation |
foremerge work start INTENT_ID --agent AGENT_ID |
| Ask who is changing it |
foremerge work query --scope KIND:KEY |
| See what every agent is doing |
foremerge status |
| Preflight a plan |
foremerge conflicts check --intent TEXT --scope KIND:KEY=OPERATION |
| Record what you concluded |
foremerge assess record --agent ID --intent ID --related-intent-id ID --verdict V --rationale TEXT --action A |
| Send coordination |
foremerge coordinate send --from ID --to ID --message TEXT |
| Watch semantic events |
foremerge work watch --after-seq 0 |
| Log in and link through device authorization |
foremerge cloud login --base-url URL |
| Link a cloud project |
foremerge cloud link --project ID --base-url URL |
| Inspect cloud lag/coverage |
foremerge cloud status |
| Deliver already-queued cloud commands |
foremerge cloud flush |
| Pull verified cloud state |
foremerge cloud sync |
| Revoke and remove a connector credential |
foremerge cloud logout |
Run foremerge <command> --help for the complete current flags. Global flags
such as --json, --cwd, and --database may appear before or after
subcommands.
Foremerge Cloud connector
The first cloud connector links one Git repository to a project, verifies the
cloud event sequence and hash chain, caches those canonical events in SQLite,
reduces canonical agent registrations and intent publications into typed local
projections, and publishes those same two mutations through a durable receipt
barrier. The standalone workflow remains unchanged when the repository is
unlinked:
foremerge cloud login --base-url https://cloud.foremerge.com
foremerge --json cloud flush
foremerge --json cloud sync
foremerge --json cloud status
foremerge cloud logout
Interactive login stores access/refresh material only in the operating-system
credential store and puts a nonsecret keyring:fmc_... locator in repository
configuration. There is no plaintext fallback when the keyring is unavailable.
Explicit env:FOREMERGE_CLOUD_TOKEN references remain supported for hosted/CI
use. Tokens never enter Git configuration, SQLite, output, errors, or logs.
Link config version 2 points at an immutable SQLite generation binding the
service, tenant, connector, project, and origin. Refresh uses a per-link SQLite
lease and a stable keyring-only rotation id, so concurrent callers cannot race
and a replayed rotation response retains its original authoritative issuance
time. Login persists its device flow before prompting, resumes the same device
code after a restart or truncated response, and performs one idempotent refresh
before link activation. The service revokes an unacknowledged connector when
its consumed-device replay is pruned; the subsequent rotation replay remains a
bounded recovery window (currently about ten minutes) pending a distinct
pre-alpha rotation acknowledgement. cloud logout recovers any in-flight rotation before no-oracle revocation
and removes the local keyring item only after remote acceptance; explicitly
named --local-only cleanup is available when offline. Login also writes a
nonsecret pending-auth recovery pointer before activating the link. If link
activation and immediate revocation both fail, cloud status exposes that
state and cloud logout can retry with the keyring-held token even though no
link exists. Keyring-backed links require logout before unlink; environment
links retain the existing unlink behavior. When retained events no longer
cover the local cursor, sync verifies a tenant-bound Ed25519 snapshot from the
server's well-known key before pulling the remaining tail. Status reports both
the verified-cache and applied-projection heads, their lag, staleness,
retention, project/head metadata, and whether coverage starts at genesis or a
verified snapshot.
For those two mutations, the local attempted record and immutable command
envelope commit in one SQLite transaction. CLI, MCP, and loopback JSON API
calls report success only after a matching immutable cloud receipt; if delivery
is unavailable, they return CLOUD_MUTATION_DEGRADED while preserving the
local attempt and queued command for cloud flush recovery. Automatic delivery
uses one two-second wall-clock deadline across HTTP retries and backoff, then
releases its lease to immediately retryable pending state. Explicit
cloud flush retains its independently configurable timeout. Agent envelopes
exclude the local worktree path. Intent envelopes exclude free-form rationale
and metadata, retaining only stable ids, task/summary, normalized scopes, and
dependency ids. Both command families omit the project-version precondition so
independent origins may be authoritatively re-evaluated from the same observed
head; the envelope and durable outbox retain optional CAS for future
state-sensitive commands.
This connector does not upload existing local history or publish/reduce
other lifecycle mutations. Canonical agent.registered and
intent.published events, plus the corresponding Agent/Intent snapshot
projections, are applied without appending duplicate local audit events.
Unknown event kinds remain verified in the immutable cache but fail closed
without advancing the projection cursor. A retention snapshot likewise remains
verified and cached, but is not reported as applied when its claims, conflicts,
or provider-obs
Foremerge — открытый протокол координации ИИ-кодинг-агентов, работающий поверх Git. Он позволяет нескольким агентам в отдельных worktree декларировать намеченные изменения, чтобы конфликтующие планы выявлялись до написания кода, а не только после пересечения файлов.