naw103/foremerge: Catch intent conflicts earlier than code conflicts. The open-source coordination protocol for coding brokers, constructed above Git. · GitHub

Foremerge is the open-source coordination protocol for coding brokers, constructed
above Git. Agents hold remoted worktrees whereas sharing intent, semantic
claims, dependencies, provisional ChangeSets, choices, validation, and
provenance.

Status: Foremerge 0.5.0 is a pre-1.0, local-first MVP. The CLI, JSON API,
MCP server, SQLite retailer, deterministic confrontation detector, and
verification-gated lifecycle are applied. Public schemas should still
change. Published benchmark outcomes don’t but exist, and coordination
between machines is exterior this venture’s scope.

Say you’ve got two AI brokers engaged on the identical venture on the similar time. Each
one will get its personal copy of the code, in order that they by no means struggle over information. Both end.
Both look right. Then you discover they undid one another’s work.

Git can not warn you about that, as a result of Git compares textual content and never intent. It
will cease you when two brokers edit the identical a part of the identical file. What it
can not see is 2 edits which might be every completely cheap on their very own and
land in several information. If one agent strikes each caller onto a brand new
StripePaymentService whereas one other provides PayPal assist to the outdated
PaymentService, nothing overlaps, so Git merges each with out criticism and
the PayPal work is left stranded on a category nothing calls any extra.

Foremerge fixes this by having brokers announce what they’re about to do,
earlier than they do it.

1. Each agent says what it’s about to the touch. Not the code, simply the
   goal, like “I’m going to alter the sendEmail perform.”
2. Every agent reads from one shared listing. It is a small database inside
   your venture’s .git folder, so each agent in your machine sees the identical
   image, whether or not it’s Claude, Codex, or Cursor.
3. If two plans collide, you hear about it immediately. Foremerge names the
   two brokers, explains why their plans conflict, and suggests the right way to cut up the
   work. Both worktrees are nonetheless clear at that time, so no work must be
   thrown away.

Think of it as a shared whiteboard. Before an agent begins, it writes down what
it’s about to work on, and it reads what everybody else already wrote.

Two issues Foremerge intentionally doesn’t do. It by no means locks a file or blocks
an agent, as a result of a single crashed agent would then stall the entire fleet, so
the warnings are advisory and also you keep in cost. And it by no means asks a mannequin to
choose conflicts, so the identical inputs all the time produce the identical reply.

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

These brokers can work in several bushes with out touching the identical line. The
plans nonetheless collide: one removes the extension level whereas the opposite relies on
it.

Both brokers declare the identical image:PaymentService scope, one saying it is going to
substitute it and the opposite that it’s going to lengthen it. Foremerge compares these
two declarations earlier than both writes code, raises a HIGH advisory, and
suggests coordinating on a secure abstraction akin to PaymentProvider. That
suggestion is explainable proof, not an automated structure resolution or a
arduous lock.

Because the operation is said relatively than learn out of the abstract, it does
not matter how both agent phrased its plan. “Consolidate funds onto
Stripe” and “Replace PaymentService with Stripe” attain the identical verdict.

Git stays the sturdy repository. Foremerge provides the lacking shared
consciousness above it.

Rendered from the precise confrontation fields captured by the 0.1.0
release-binary run in
examples/terminal-session.txt. The displayed
command makes use of the proven jq filter; output is abridged for readability.

Paste this into Claude Code, Codex, or Cursor from contained in the repository you
wish to coordinate:

Set up Foremerge on this repository so we are able to coordinate parallel brokers.

1. Install it:      curl -fsSL https://foremerge.com/install.sh | sh
2. Initialize:      foremerge init
3. Wire this consumer and any others in use: foremerge setup all
4. Register the examine I must be validated towards, for instance:
                    foremerge checks set take a look at -- cargo take a look at --all-targets
5. Confirm:         foremerge physician --client all

Then learn the Foremerge ability that step 3 put in for this consumer and observe
it to any extent further: publish your intent with semantic scopes earlier than enhancing, declare
the scope, and examine for conflicts earlier than you begin.

Adjust step 4 to no matter this repository’s actual take a look at command is. Step 3 asks
the consumer to allow an MCP server, so it is going to immediate you earlier than doing so. The
Codex registration is person degree, however one registration serves each repository:
begin Codex contained in the repository you need it to coordinate.

You want a current Git and jq. Install a prebuilt, checksum-verified launch
binary (macOS and Linux; the script installs to ~/.native/bin):

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

Or construct from supply with Rust 1.85+: cargo set up --locked --git https://github.com/naw103/foremerge foremerge, or cargo set up --locked --path . from a checkout. Windows binaries are on the
releases page. To replace,
improve the identical means you put in, then re-run foremerge setup and restart
your agent purchasers; Upgrading Foremerge
explains why every step issues. Then, contained in the repository you wish to
coordinate:

foremerge init
foremerge physician

The installer, the discharge archives and cargo set up all carry each names
from 0.4.0 onward. If one thing else in your PATH already solutions to fmg, the
installer leaves it alone and says so relatively than shadowing it.

Install the native ability and MCP entry for any purchasers used on this repository,
then outline the trusted checks brokers could request by identify:

foremerge setup all
foremerge checks set take a look at -- cargo take a look at --all-targets
foremerge physician --client all

Acceptance is verification-gated: Foremerge runs the examine itself relatively than
taking an agent’s phrase for it. Pick a examine that’s quick and that might truly
catch a damaged handoff, akin to a construct or a typecheck, relatively than a full CI
suite; this gate decides whether or not different brokers could deal with the work as accomplished, and it
doesn’t substitute CI. If this repository has nothing significant to confirm, say so
as soon as relatively than registering a examine that all the time passes:

foremerge checks coverage advisory

Work accepted that means is recorded as UNVERIFIED with the rationale, so the audit
path by no means implies a examine ran when none did. foremerge physician studies
whether or not the registered checks can truly run right here, which issues in agent
worktrees, as a result of dependency directories are often gitignored and
git worktree add won’t create them.

Use setup codex, setup claude, or setup cursor for one consumer. Setup
preserves unrelated configuration (together with key order in venture MCP JSON).
Upgrading Foremerge refreshes its personal unedited ability file in place, however a ability
file you edited, or a differing Foremerge MCP entry, isn’t changed except
you explicitly cross --force. setup all makes an attempt each consumer and studies every
consequence, exiting nonzero if any failed. The Codex MCP registration is user-level
and serves each repository, resolved from the listing Codex is began in;
see agent client setup.

init creates native coordination state beneath the repository’s Git widespread
listing. It doesn’t change tracked information. The following no-worktree periods
are sufficient to train pre-code detection; actual coding brokers ought to register
their remoted worktrees and precise mannequin identifiers.

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

STRIPE_RESULT=$(
  foremerge --json intent publish 
    --agent "$STRIPE_AGENT" 
    --task "modernize-payments" 
    --summary "Replace PaymentService with StripePaymentService" 
    --scope image:PaymentService=substitute
)
STRIPE_INTENT=$(printf '%sn' "$STRIPE_RESULT" | jq -er '.information.intent.id')

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

PAYPAL_RESULT=$(
  foremerge --json intent publish 
    --agent "$PAYPAL_AGENT" 
    --task "add-paypal" 
    --summary "Add PayPal assist to PaymentService" 
    --scope image:PaymentService=lengthen
)
PAYPAL_INTENT=$(printf '%sn' "$PAYPAL_RESULT" | jq -er '.information.intent.id')

printf '%sn' "$PAYPAL_RESULT" |
  jq '.information.conflicts[] | {type, severity, scope, rationalization, suggestion}'

printf '%sn' "$PAYPAL_RESULT" |
  jq '.information.related_work[] | {agent, abstract, asserted, overlap}'

The first command prints the dwell discovering out of your native run. The second
prints related_work: the opposite agent’s intent and each overlapping scope
with each declared operations. Foremerge states what overlaps; you determine what
it means and file that with foremerge assess file. No information must
change first. Inspect the captured, clearly labeled transcript in
examples/terminal-session.txt.

Claims add possession context with out blocking both agent:

foremerge --json work declare 
  --agent "$STRIPE_AGENT" 
  --intent "$STRIPE_INTENT" 
  --scope image:PaymentService 
  --reason "Changing the supplier boundary" >/dev/null

foremerge --json work declare 
  --agent "$PAYPAL_AGENT" 
  --intent "$PAYPAL_INTENT" 
  --scope image:PaymentService 
  --reason "Adding one other supplier" |
  jq '.information | {advisory_only, warnings}'

foremerge --json work question --scope image:PaymentService |
  jq '.information[] | {agent: .agent.identify, intent: .intent.abstract, open_conflicts}'

Both claims succeed. The second response consists of an overlap warning as a result of a
declare is a leased advisory, by no means unique possession.

Recorded towards the launched 0.4.0 binary; each command and its output is actual.

  coding agent A                                  coding agent B
        |                                               |
  remoted worktree A                            remoted worktree B
        |                                               |
        +--------- semantic occasions, not edits ----------+
                              |
                    CLI / MCP / JSON API
                              |
                     Foremerge service
                    /        |        
       SQLite coordination   git CLI   validation argv
       in        |           |
                             Git repository /
                     sturdy commits and refs

Every frontend makes use of the identical service and retailer. The semantic graph is:

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

Mutations replace typed SQLite projections, materialize graph edges, and append a
hash-chained semantic occasion in a single transaction. The log is helpful tamper
proof; it’s not a distant id signature or distributed consensus.

Foremerge resolves the Git widespread listing and shops its default database at:

Linked worktrees share that widespread listing despite the fact that their checked-out
information are separate. Create a worktree with Foremerge’s skinny wrapper round
inventory 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 identical repository sees the registered agent and its
intents instantly. You can override storage with --database PATH or
FOREMERGE_DB, however each native agent should level on the similar database to share
state. The MVP doesn’t replicate SQLite throughout machines; don’t infer
distributed security from a network-mounted database.

Foremerge snapshots Git state for ChangeSet fingerprints and accepted refs. It
doesn’t mechanically merge, rebase, cherry-pick, push, or replace a goal
department.

INTENT ─declare→ CLAIMED ─begin→ IN_PROGRESS ─publish→ PROVISIONAL
       ─validate present fingerprint→ VALIDATED
       ─settle for gates→ ACCEPTED ─file Git ref→ COMMITTED

Supported scope sorts are:

image api schema config infra take a look at migration env file part contract area

Publish the narrowest helpful semantic scope. File paths alone miss API,
configuration, schema, development projects, and cross-language collisions.

Common instructions:

Run foremerge --help for the whole present flags. Global flags
akin to --json, --cwd, and --database could seem earlier than or after
subcommands.

A ChangeSet captures the agent/mannequin, job and intent, affected
information/symbols/contracts, dependencies, implementation abstract, reported exams,
choices, provenance, worktree, fingerprint, standing, and Git ref.
The accepted candidate and its later touchdown commit are retained individually as
accepted_commit and integration_commit.

The trustworthy integration order is:

1. Publish intent, declare semantic scope, and mark implementation in progress.
2. Work and commit on the remoted agent department.
3. Publish a ChangeSet for that clear candidate.
4. Ask Foremerge to execute validation towards its actual fingerprint.
5. Resolve excessive conflicts, then settle for the still-clean, still-validated ref.
6. Integrate with odd Git or a pull request.
7. Record the sturdy integration commit in Foremerge.

foremerge work declare 
  --agent "$AGENT_ID" 
  --intent "$INTENT_ID" 
  --scope part:funds
foremerge work begin "$INTENT_ID" --agent "$AGENT_ID"

# Implement the change and commit it on this remoted department earlier than publishing.
CHANGESET_ID=$(
  foremerge --json changeset publish 
    --agent "$AGENT_ID" 
    --intent "$INTENT_ID" 
    --summary "Introduce PaymentProvider and StripePaymentProvider" 
    --file src/funds.rs 
    --symbol PaymentProvider 
    --symbol StripePaymentProvider 
    --contract payment-provider 
    --provenance-json '{"supply":"coding-agent"}' 
    --git-ref HEAD 
    --worktree "$PWD" |
  jq -er '.information.id'
)

foremerge changeset validate "$CHANGESET_ID" 
  --worktree "$PWD" 
  -- cargo take a look at --all-targets

foremerge changeset settle for "$CHANGESET_ID" --git-ref HEAD

# Integrate with odd Git, then file the commit that really landed.
foremerge changeset commit "$CHANGESET_ID" --git-ref important

Agent-reported --reported-test COMMAND=STATUS values are provenance solely.
They don’t fulfill acceptance. Foremerge-owned validation data the command
argument vector, exit standing, output, period, and candidate fingerprint. Any
detected change after validation makes that try non-authoritative, however its
output and changed-path diagnostic stay queryable with changeset makes an attempt.

For trusted checks that generate disposable untracked output, an operator could
set actual or directory-prefix guidelines with out altering tracked information:

foremerge validation-exclusions set 
  --path protection.log 
  --path goal/validation-reports/

The normalized coverage digest is a part of the candidate fingerprint, tracked
modifications are by no means excludable, MCP can not change the coverage, and generated information
should nonetheless be eliminated earlier than acceptance. See
ADR 0001.

Acceptance additionally requires a clear worktree and no unresolved HIGH confrontation,
except the caller intentionally makes use of the seen --allow-high-conflicts
override along with --override-reason "...". Prefer resolving a confrontation
with an express rationale. Acceptance creates
refs/foremerge/accepted/; it doesn’t merge code.

Validation instructions run as trusted native code together with your operating-system
permissions. Foremerge doesn’t sandbox them.

Run foremerge mcp over stdio. MCP doesn’t require the HTTP daemon; each are
adapters over the identical database.

Start from the legitimate minimal config in
examples/mcp-config.json. It assumes the consumer
launches foremerge with the repository as its working listing. Clients
with no repository working-directory setting ought to cross an absolute
--database earlier than mcp; derive the Git widespread listing as a substitute of assuming
{that a} linked worktree’s .git is a listing.

See agent client setup for the installer, native ability
areas, client-specific MCP information, diagnostics, and protected alternative guidelines.
See MCP setup for transport habits, schemas, named checks,
instance inputs, and multi-worktree configuration.

Source clones embrace equal abilities in .codex/abilities, .claude/abilities,
.cursor/abilities, the transportable .brokers/abilities location, and the Claude Code
plugin, plus transportable Claude and Cursor MCP templates. A Cargo set up
embeds the canonical ability so foremerge setup can set up it into one other
repository with out copying this supply tree.

The daemon defaults to authenticated loopback HTTP on
http://127.0.0.1:47811. init creates a bearer token with non-public file
permissions the place the platform helps them.

In one terminal:

In one other terminal, learn the token path from Foremerge relatively than guessing
it:

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

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

Do not print, commit, or share the token. /healthz is database-free course of
liveness and /readyz is a bounded non-waiting retailer probe; each are public.
Every /v1 route, together with the paged event-chain audit, requires the token except
the daemon was intentionally began with --no-auth for a trusted native take a look at.
The MVP refuses non-loopback binds and isn’t a hardened multi-tenant service.

The CLI escape hatch foremerge request reads native auth mechanically. A
runnable curl walkthrough is in
examples/api-requests.sh; the complete route and error
reference is JSON API.

• Conflict detection is deterministic and explainable, however heuristic. It can
  miss synonymous ideas and warn on appropriate work.
• Claims warn; they by no means lock information, symbols, or brokers.
• Passing validation proves solely that the recorded command handed for the
  recorded fingerprint, not that the take a look at plan was full.
• Git refs and course of outcomes are stronger proof than self-reported mannequin,
  immediate, or take a look at prose.
• The occasion chain detects modifications contained in the retained chain; it’s not a
  signature, distant attestation, or exterior checkpoint.
• Local SQLite isn’t shared-mode consensus, and the loopback bearer token is
  not a public deployment safety mannequin.
• There are executable benchmark fixtures, a reproducible question harness, and a
  benchmark plan, however no revealed
  coordinated-vs-uncoordinated efficiency outcomes but.
• Foremerge doesn’t substitute code overview, structure possession, CI, safety
  scanning, Git internet hosting guidelines, or backups.

Read the whole limitations and trust model earlier than
utilizing Foremerge as an integration gate.

Also see the changelog, security policy, and
code of conduct.

Contributions are welcome, particularly protocol suggestions on scope vocabulary,
confrontation proof, ChangeSet provenance, and verification coverage. Read
CONTRIBUTING.md, then run the whole native gate:

Foremerge is licensed beneath the Apache License 2.0.