Skip to main content
Glama

CI crates.io License: Apache-2.0

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.7.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.

Related MCP server: agent-locks

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.

Terminal rendering of an actual Foremerge release demo detecting the PaymentService conflict before either worktree changed

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.

Real terminal recording: two agents declare intents on symbol:PaymentService and Foremerge raises the HIGH destructive_vs_additive finding before either writes code

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

Run foremerge <command> --help for the complete current flags. Global flags such as --json, --cwd, and --database may appear before or after subcommands.

ChangeSets and the verification gate

A ChangeSet captures the agent/model, task and intent, affected files/symbols/contracts, dependencies, implementation summary, reported tests, decisions, provenance, worktree, fingerprint, status, and Git ref. The accepted candidate and its later landing commit are retained separately as accepted_commit and integration_commit.

The honest integration order is:

  1. Publish intent, claim semantic scope, and mark implementation in progress.

  2. Work and commit on the isolated agent branch.

  3. Publish a ChangeSet for that clean candidate.

  4. Ask Foremerge to execute validation against its exact fingerprint.

  5. Resolve high conflicts, then accept the still-clean, still-validated ref.

  6. Integrate with ordinary Git or a pull request.

  7. Record the durable integration commit in Foremerge.

foremerge work claim \
  --agent "$AGENT_ID" \
  --intent "$INTENT_ID" \
  --scope component:payments
foremerge work start "$INTENT_ID" --agent "$AGENT_ID"

# Implement the change and commit it on this isolated branch before publishing.
CHANGESET_ID=$(
  foremerge --json changeset publish \
    --agent "$AGENT_ID" \
    --intent "$INTENT_ID" \
    --summary "Introduce PaymentProvider and StripePaymentProvider" \
    --file src/payments.rs \
    --symbol PaymentProvider \
    --symbol StripePaymentProvider \
    --contract payment-provider \
    --provenance-json '{"source":"coding-agent"}' \
    --git-ref HEAD \
    --worktree "$PWD" |
  jq -er '.data.id'
)

foremerge changeset validate "$CHANGESET_ID" \
  --worktree "$PWD" \
  -- cargo test --all-targets

foremerge changeset accept "$CHANGESET_ID" --git-ref HEAD

# Integrate with ordinary Git, then record the commit that actually landed.
foremerge changeset commit "$CHANGESET_ID" --git-ref main

Agent-reported --reported-test COMMAND=STATUS values are provenance only. They do not satisfy acceptance. Foremerge-owned validation records the command argument vector, exit status, output, duration, and candidate fingerprint. Any detected change after validation makes that attempt non-authoritative, but its output and changed-path diagnostic remain queryable with changeset attempts.

For trusted checks that generate disposable untracked output, an operator may set exact or directory-prefix rules without changing tracked files:

foremerge validation-exclusions set \
  --path coverage.log \
  --path target/validation-reports/

The normalized policy digest is part of the candidate fingerprint, tracked changes are never excludable, MCP cannot change the policy, and generated files must still be removed before acceptance. See ADR 0001.

Acceptance also requires a clean worktree and no unresolved HIGH conflict, unless the caller deliberately uses the visible --allow-high-conflicts override together with --override-reason "...". Prefer resolving a conflict with an explicit rationale. Acceptance creates refs/foremerge/accepted/<changeset-id>; it does not merge code.

Validation commands run as trusted local code with your operating-system permissions. Foremerge does not sandbox them.

Agent clients and MCP: complete lifecycle tools

Run foremerge mcp over stdio. MCP does not require the HTTP daemon; both are adapters over the same database.

Tool

Purpose

register_agent

Record agent, model, capabilities, and worktree provenance

publish_intent

Announce planned work, declare what it does to each scope, and receive conflicts plus related work to assess

record_assessment

Record what you concluded about one related intent and what you will do

claim_work

Create leased advisory claims on semantic scopes

query_work

Find agents, intents, claims, ChangeSets, and conflicts

check_conflicts

Check a published or provisional intent before code changes

publish_changeset

Record implementation, tests, decisions, and Git provenance

coordinate_with_agent

Send a durable message linked to a conflict or ChangeSet

start_work

Advance claimed work into implementation

resolve_conflict

Record an audited resolution for a durable conflict

run_verification

Run a trusted repository check by name, never raw MCP argv

accept_changeset

Apply final conflict, dependency, validation, and Git gates

record_commit

Record the actual Git integration commit

discard_work

Close abandoned work, or work that landed without acceptance, releasing claims and blockers

list_agents

Read registered agent provenance

get_intent

Read one intent and current conflict snapshot

get_changeset

Read one ChangeSet and Git/provenance state

status

Read one consistent coordinator status snapshot

Start from the valid minimal config in examples/mcp-config.json. It assumes the client launches foremerge with the repository as its working directory. Clients without a repository working-directory setting should pass an absolute --database before mcp; derive the Git common directory instead of assuming that a linked worktree's .git is a directory.

See agent client setup for the installer, native skill locations, client-specific MCP files, diagnostics, and safe replacement rules. See MCP setup for transport behavior, schemas, named checks, example inputs, and multi-worktree configuration.

Source clones include equivalent skills in .codex/skills, .claude/skills, .cursor/skills, the portable .agents/skills location, and the Claude Code plugin, plus portable Claude and Cursor MCP templates. A Cargo installation embeds the canonical skill so foremerge setup can install it into another repository without copying this source tree.

Local JSON API

The daemon defaults to authenticated loopback HTTP on http://127.0.0.1:47811. init creates a bearer token with private file permissions where the platform supports them.

In one terminal:

foremerge daemon

In another terminal, read the token path from Foremerge rather than guessing it:

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

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

Do not print, commit, or share the token. /healthz is database-free process liveness and /readyz is a bounded non-waiting store probe; both are public. Every /v1 route, including the paged event-chain audit, requires the token unless the daemon was deliberately started with --no-auth for a trusted local test. The MVP refuses non-loopback binds and is not a hardened multi-tenant service.

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

What the MVP deliberately does not claim

  • Conflict detection is deterministic and explainable, but heuristic. It can miss synonymous concepts and warn on compatible work.

  • Claims warn; they never lock files, symbols, or agents.

  • Passing validation proves only that the recorded command passed for the recorded fingerprint, not that the test plan was complete.

  • Git refs and process results are stronger evidence than self-reported model, prompt, or test prose.

  • The event chain detects changes inside the retained chain; it is not a signature, remote attestation, or external checkpoint.

  • Local SQLite is not shared-mode consensus, and the loopback bearer token is not a public deployment security model.

  • There are executable benchmark fixtures, a reproducible query harness, and a benchmark plan, but no published coordinated-vs-uncoordinated performance results yet.

  • Foremerge does not replace code review, architecture ownership, CI, security scanning, Git hosting rules, or backups.

Read the complete limitations and trust model before using Foremerge as an integration gate.

Documentation

Document

What it answers

Architecture

Why one Rust binary, SQLite, Git CLI, and shared common-dir state?

Protocol

What do agents publish and when?

State model

Which transitions and invariants gate work?

Conflict detection

Which deterministic rules produce findings and suggestions?

Git integration

How do fingerprints, worktrees, and accepted refs behave?

Agent clients

How do Codex, Claude Code, and Cursor discover the skill and MCP server?

MCP setup

How do clients configure and call the 18 lifecycle/read tools?

JSON API

Which routes, request bodies, auth, and errors are shipped?

OpenAPI schema

What is the machine-readable HTTP contract?

Benchmark plan

How will coordinated and uncoordinated runs be compared?

Validation exclusion ADR

Which generated paths may validation ignore, and why?

Roadmap

What is current, next, later, or a non-goal?

Limitations

What does the MVP not guarantee?

Brand

Which mark, colors, type, icons, and CLI output rules apply to any Foremerge surface?

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

Contributing and license

Contributions are welcome, especially protocol feedback on scope vocabulary, conflict evidence, ChangeSet provenance, and verification policy. Read CONTRIBUTING.md, then run the complete local gate:

make verify

Foremerge is licensed under the Apache License 2.0.

Available Tools

18 tools
accept_changesetAccept a validated ChangeSetA

Accept a ChangeSet as done so other agents may build on it. Use this after run_verification passes; use record_commit later, once the work has actually landed on the target branch. Foremerge re-checks every gate before accepting: the worktree must be clean and unchanged since publication, verification must have passed (unless the repository's policy is advisory and nothing was verified), no HIGH conflict on the intent may be OPEN or COORDINATING (resolve_conflict clears an agreed one, and discard_work dismisses the conflicts of work you drop), and every intent in the ChangeSet's dependencies must already be accepted, with its accepted commit, or once committed its recorded integration commit, in this commit's history. On success it marks the ChangeSet and intent ACCEPTED, pins the commit as accepted_commit, writes refs/foremerge/accepted/<changeset_id>, and returns the updated ChangeSet. A failed gate returns an error naming it (CHECK_FAILED, BLOCKING_CONFLICT, UNSATISFIED_DEPENDENCY, STALE_CHANGESET, INVALID_TRANSITION) and changes nothing. Overriding a gate is an operator action on the CLI or HTTP API and is refused over MCP, so ask a human when a gate should be bypassed.

Inputs: changeset_id (required), git_ref.

check_conflictsCheck intent conflictsA
Read-only

Ask whether planned work collides with other agents' active work, before any change exists. Read-only: nothing is stored, so use it while only planning. It runs the same comparison as publish_intent: overlapping scopes, not only identical ones, and the declared operations on each. Pass intent_id alone to list the persisted OPEN or COORDINATING conflicts on a published intent (use this before publish_changeset and before run_verification, since conflicts are raised when the later intent publishes). Pass intent text with scopes, or intent_id with replacement scopes, for a what-if check against every intent from INTENT through VALIDATED, excluding ACCEPTED, COMMITTED and DISCARDED; those findings carry ephemeral eph_ ids and are not recorded. Returns conflicts (each with severity, explanation, evidence and a suggested coordination step), checked_intents, blocking (true when any finding is HIGH), ephemeral (true when the ids are per-call eph_ ids), as_of_event (the ledger event sequence the read reflects), and the active policy. To record a decision about overlap, use record_assessment or resolve_conflict instead.

Inputs: intent, scopes, agent_id, intent_id.

claim_workClaim semantic workA

Tell other agents you are working on specific scopes of your own intent, for a limited time. Use this after publish_intent and record_assessment, and before start_work. Claims are advisory and never lock: if any other intent, another of yours included, holds a live claim on a matching scope (symbols match loosely by name), you still get the claim, and a claim-overlap conflict is recorded and returned as a warning. The first claim moves the intent from INTENT to CLAIMED. Claiming a scope the intent already holds renews its lease instead of adding a second claim, which is how long-running work keeps its claims. Only the intent's owner may claim, and only while the intent is INTENT, CLAIMED or IN_PROGRESS. Returns the created or renewed claims, overlap warnings, advisory_only: true, and scope_warnings when a symbol key will lose its class.

Inputs: scopes (required), agent_id (required), intent_id (required), reason, +1 more.

coordinate_with_agentCoordinate with another agentA

Send a stored message to another registered agent, usually to agree how two overlapping pieces of work should coexist. Use it when check_conflicts or related_work shows a clash you need the other agent to act on; afterwards, a party to the conflict records the agreement with resolve_conflict, naming this message's id. Linking a conflict_id moves that conflict from OPEN to COORDINATING. The message is appended to a durable log with status UNREAD; it does not interrupt or control the other agent. No MCP tool reads messages: the recipient reads them with the CLI, foremerge coordinate inbox. Returns the stored message, including its msg_ id.

Inputs: message (required), to_agent_id (required), from_agent_id (required), conflict_id, +1 more.

discard_workDiscard workA
Destructive

Close one of your own intents that you will not take through accept_changeset. Call it before you stop working, whenever the intent is still open: an intent never closes itself, and an open one is compared against every later intent on the same scopes. Two cases. Work that will not be finished, for example a duplicate or work another agent took over: pass a reason. Work that reached Git without a passing named check, so it cannot be accepted: pass landed_ref as well, naming the commit or branch it landed in. Either way it sets the intent to DISCARDED, releases all of its active claims, and dismisses its OPEN or COORDINATING conflicts so they stop blocking the other party. With landed_ref the commit is checked and recorded, but the intent still ends DISCARDED, not ACCEPTED: nothing here says the work was verified. The history stays in the event log, but a discarded intent cannot be resumed; publish a new intent instead. Only the owner may discard, and not once the intent is ACCEPTED, COMMITTED or already DISCARDED. Returns the updated intent. To agree that two intents can coexist, use resolve_conflict instead.

Inputs: reason (required), agent_id (required), intent_id (required), landed_ref.

get_changesetGet a ChangeSetA
Read-onlyIdempotent

Read one ChangeSet by id. Use it to check a ChangeSet's status (PROVISIONAL, VALIDATED, ACCEPTED, COMMITTED or SUPERSEDED), its fingerprint, and its commit provenance: accepted_commit, pinned at acceptance and never changed, and integration_commit, set by record_commit. Read-only. Use get_intent for the work item itself. To find an id, status lists PROVISIONAL, VALIDATED and ACCEPTED ChangeSets, and query_work shows each intent's latest one.

Inputs: id (required).

get_intentGet an intentA
Read-onlyIdempotent

Read one intent by id, with its owning agent and the count and ids of its OPEN or COORDINATING conflicts (check_conflicts with intent_id shows severity). Use it to see an intent's current status (INTENT, CLAIMED, IN_PROGRESS, PROVISIONAL, VALIDATED, ACCEPTED, COMMITTED or DISCARDED), declared scopes and depends_on, for example before assessing someone else's related work. Read-only. Use query_work to search intents by agent, status or scope, and status for everything at once.

Inputs: id (required).

list_agentsList coding agentsA
Read-onlyIdempotent

List every registered agent in registration order, with its id, name, model, capabilities, worktree, Git branch and head at registration, and status. Read-only and takes no arguments. Use it to find the agent id of another participant before coordinate_with_agent. Use status for the active agents alongside their current work.

Inputs: no named parameters.

publish_changesetPublish a provisional ChangeSetA

Record a finished unit of implementation for your intent so it can be verified and accepted. Use it once the change is committed in your worktree, after check_conflicts and before run_verification. Foremerge snapshots the worktree (defaulting to your registered one), resolves the candidate commit and its diff base, and stores a fingerprint that verification and acceptance are later checked against. files and symbols are inferred only from uncommitted changes, so list them yourself for committed work. The ChangeSet starts PROVISIONAL and the intent becomes PROVISIONAL. Publishing again while the previous ChangeSet is PROVISIONAL or VALIDATED creates a new one, marks the old one SUPERSEDED, and resets verification. Only the intent's owner may publish, while the intent is CLAIMED, IN_PROGRESS, PROVISIONAL or VALIDATED. Git itself is not modified. Returns the ChangeSet, including its chg_ id, fingerprint, and open_conflicts on the intent at that moment.

Inputs: summary (required), agent_id (required), intent_id (required), files, +9 more.

publish_intentPublish intentA

Announce work you are about to do, and the scopes it will change, before creating or editing any file meant for the repository, documents included. It is the first write for a task you are committed to, after register_agent; while only planning, use check_conflicts, which stores nothing. The intent is stored with status INTENT and compared against every other active intent. Returns the intent (with its int_ id), any conflicts detected immediately, warnings (for example no scopes declared, or a symbol key that will lose its class), and related_work: active intents, your own others included, that may relate to yours. Entries with asserted: true are collisions with both declared operations stated; the rest are candidates, with why_surfaced saying why. Assess each related_work entry and call record_assessment before changing files, then claim_work and start_work. Use check_conflicts instead for a what-if check that stores nothing.

Inputs: task (required), summary (required), agent_id (required), scopes, +3 more.

query_workQuery active workA
Read-onlyIdempotent

Search intents by owner, status or scope, to answer questions like who is changing this symbol, or which work still has open conflicts. Read-only. Each result joins an intent to its agent, its claims, its latest ChangeSet (id and full object), the ids of intents that depend on it, and its count of OPEN or COORDINATING conflicts. Results are an array, capped by limit. With no filters it returns intents of every status, including finished ones. Use get_intent when you already have an id, and status for a grouped overview of everything at once.

Inputs: limit, scope, status, agent_id.

record_assessmentRecord an assessment of related workA

Record what you concluded about one entry from related_work. Foremerge states which scopes overlap and how the declared operations relate; deciding what that means is yours. Call this once per related intent, after publish_intent and before you change files. Each call appends a new assessment rather than replacing an earlier one, and changes no statuses: it does not open, resolve or dismiss conflicts. Act on the verdict with coordinate_with_agent, resolve_conflict or discard_work as needed. Only the intent's owner may assess it. Returns the stored assessment with its asm_ id.

Inputs: action (required), verdict (required), agent_id (required), intent_id (required), +2 more.

record_commitRecord integration commitA

Record where accepted work finally landed, after it has been merged through ordinary Git or a pull request. Use it last, after accept_changeset and the merge. The commit must have the accepted commit in its history or, after a squash or rebase merge, hold every change the candidate made, checked path by path against their merge base; otherwise the call fails with TARGET_DIVERGED naming what is missing. On success it stores integration_commit, moves the ChangeSet to COMMITTED, and returns the updated ChangeSet, whose provenance.integration.method says how containment was shown (ancestor or content). accepted_commit is kept unchanged, so the record shows both what was verified and where it landed. Foremerge does not merge or push anything itself.

Inputs: git_ref (required), changeset_id (required).

register_agentRegister coding agentA

Register yourself as a participant and get the agent id every other write tool needs. Call it once at the start of each session, before publish_intent. Every call creates a new agent record, even for a name already in use; a warning is returned when an active agent with the same name and worktree exists, because that record's intents cannot be claimed by the new one. Passing a worktree records its Git branch and head; it must be inside the repository this server is bound to, normally the one it was launched in, or it is rejected with INVALID_INPUT. Returns the agent, including its agt_ id, and any warnings.

Inputs: name (required), model, worktree, capabilities.

resolve_conflictResolve a persisted conflictA

Record an audited resolution decision for a durable cfl_* conflict so blocked work can proceed. Over MCP only an agent whose intent is a party may resolve it, and the decision is recorded under its agent id. Foremerge does not verify agreement or message ids, so either party can clear the gate alone: resolve only after the other party agrees. Use coordinate_with_agent first to reach that agreement, and discard_work instead when one side is simply dropping its work. Resolving moves the conflict to RESOLVED, which clears it from the acceptance gate for both intents; it does not change any code. It fails if the conflict is already resolved or dismissed. Returns the updated conflict.

Inputs: agent_id (required), rationale (required), resolution (required), conflict_id (required).

run_verificationRun a trusted verification checkA

Run one named check from the trusted Foremerge registry of the repository this store is bound to. Raw commands are intentionally not accepted over MCP, and the registry cannot be selected by the caller or the server's working directory. Use it after publish_changeset and before accept_changeset; acceptance relies on this result, not on tests you report yourself. The check's command runs in the ChangeSet's worktree with the registry's timeout. It may create only generated files excluded from the fingerprint: changing any other file fails with STALE_CHANGESET, and excluded files left from an earlier run fail with CHECK_FAILED before it starts. The worktree must still match the fingerprint recorded at publication, or the call fails with STALE_CHANGESET and you must publish again. A pass moves the ChangeSet to VALIDATED; a failure leaves or returns it to PROVISIONAL. Returns the validation record: whether it passed, the exit code, captured stdout and stderr, the duration, and the fingerprint it ran against.

Inputs: check (required), changeset_id (required).

start_workStart claimed workA

Mark your claimed intent as being implemented. Call it after claim_work, immediately before you begin changing files. It moves the intent from CLAIMED to IN_PROGRESS and fails in any other state, or if you do not own the intent. It does not create or renew claims; use claim_work for that. Returns the updated intent with open_conflicts, the count and ids of its OPEN or COORDINATING conflicts; check their severity with check_conflicts before going further.

Inputs: agent_id (required), intent_id (required).

statusRead coordinator statusA
Read-onlyIdempotent

Get the whole coordination picture in one call, taken from a single consistent read: active agents, intents grouped by lifecycle status, unexpired claims, the OPEN or COORDINATING conflicts someone can act on with both parties named, and ChangeSets grouped by status. Every count is complete, but each list stops at 25 entries and says how many it left out; COMMITTED and DISCARDED intents are counted, not listed, and conflicts below HIGH between work that has stopped are counted, not listed. Read-only and takes no arguments. Use it to orient at the start of a session or before choosing work. Use query_work to filter by agent, status or scope, and get_intent or get_changeset for full detail on one item, including each party's scopes.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 18 tools

    Disambiguation4/5

    The tools map to distinct lifecycle stages and resources, and the long descriptions clarify when to use each one. Some read-only tools (status, query_work, get_intent) overlap in purpose, and check_conflicts versus publish_intent both compare scopes, but the descriptions provide clear boundaries.

    Naming Consistency4/5

    Nearly every tool follows a snake_case verb_noun pattern (claim_work, publish_intent, run_verification, accept_changeset). The only clear exception is status, which is a bare noun rather than verb_noun.

    Tool Count4/5

    Eighteen tools is slightly heavy, but the domain has a rich lifecycle: registration, intent publication, claims, conflict checks, assessments, changesets, verification, acceptance, and commit recording. Each tool appears to earn its place rather than being redundant filler.

    Completeness4/5

    The surface covers the full intent and ChangeSet lifecycle, including conflict handling, verification, acceptance, commit recording, and discard paths. The notable gap is that no MCP tool reads messages from coordinate_with_agent; recipients must use the CLI inbox, which creates a workaround rather than a fully closed loop.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A filesystem-based MCP server for AI coding agents to coordinate work across git worktrees by claiming files, checking for conflicts, and logging progress without affecting the repository's git history.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for orchestrating a fleet of CLI coding agents in isolated git worktrees. It exposes tools for spawning workers, sending instructions, reviewing diffs, and merging changes, with full terminal visibility.
      7 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that enables AI coding agents to coordinate by sharing environment snapshots and diffs, surfacing overlapping work, exchanging debug-session messages, handing off tasks, and enforcing policy preflight checks.
      Elastic 2.0