Foremerge
Foremerge is an MCP coordination server for coding agents that tracks intent, claims, conflicts, ChangeSets, validation, and Git provenance above Git.
Register agents with name, model, capabilities, and worktree provenance.
Publish intents with task, summary, semantic scopes and operations; receive conflicts and related work.
Run read-only what-if conflict checks before changing code.
Record assessments of related work and coordinate with other agents via durable messages.
Claim semantic scopes as leased advisory ownership and advance work to in-progress.
Publish ChangeSets with files, symbols, contracts, decisions, dependencies, tests, and provenance.
Run trusted named verification checks against a ChangeSet fingerprint; raw commands are not accepted over MCP.
Accept validated ChangeSets after conflict, dependency, cleanliness, and verification gates, pinning accepted commits.
Record the actual integration commit after ordinary Git merge or PR.
Resolve persisted conflicts with an audited rationale or discard abandoned/unaccepted work.
Read status, query work by agent/status/scope, get intents and ChangeSets, and list agents.
Coordinates parallel coding agents working in Git repositories by tracking declared intents, semantic scopes, claims, conflicts, and changesets, helping avoid conflicts before code is written.
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.
→ | 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.0is 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.
Each agent says what it is about to touch. Not the code, just the target, like "I am going to change the
sendEmailfunction."Every agent reads from one shared list. It is a small database inside your project's
.gitfolder, 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.
Related MCP server: agent-locks
The conflict Git cannot see yet
Agent A: Replace PaymentService with StripePaymentService
Agent B: Add PayPal support to PaymentServiceThese 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 | shTwo 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 foremergeOr 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 doctorThe 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 allAcceptance 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 advisoryWork 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 refsEvery frontend uses the same service and store. The semantic graph is:
Agent → Task → Intent → Claim → Symbol → Dependency
→ ChangeSet → Test → Result → Decision → ProvenanceMutations 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.sqlite3Linked 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→ COMMITTEDSupported scope kinds are:
symbol api schema config infra test migration env file component contract domainPublish the narrowest useful semantic scope. File paths alone miss API, configuration, schema, infrastructure, and cross-language collisions.
Common commands:
Boundary | Command |
Register provenance |
|
Publish intent |
|
Claim scope |
|
Start implementation |
|
Ask who is changing it |
|
See what every agent is doing |
|
Preflight a plan |
|
Record what you concluded |
|
Send coordination |
|
Watch semantic events |
|
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:
Publish intent, claim semantic scope, and mark implementation in progress.
Work and commit on the isolated agent branch.
Publish a ChangeSet for that clean candidate.
Ask Foremerge to execute validation against its exact fingerprint.
Resolve high conflicts, then accept the still-clean, still-validated ref.
Integrate with ordinary Git or a pull request.
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 mainAgent-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 |
| Record agent, model, capabilities, and worktree provenance |
| Announce planned work, declare what it does to each scope, and receive conflicts plus related work to assess |
| Record what you concluded about one related intent and what you will do |
| Create leased advisory claims on semantic scopes |
| Find agents, intents, claims, ChangeSets, and conflicts |
| Check a published or provisional intent before code changes |
| Record implementation, tests, decisions, and Git provenance |
| Send a durable message linked to a conflict or ChangeSet |
| Advance claimed work into implementation |
| Record an audited resolution for a durable conflict |
| Run a trusted repository check by name, never raw MCP argv |
| Apply final conflict, dependency, validation, and Git gates |
| Record the actual Git integration commit |
| Close abandoned work, or work that landed without acceptance, releasing claims and blockers |
| Read registered agent provenance |
| Read one intent and current conflict snapshot |
| Read one ChangeSet and Git/provenance state |
| 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 daemonIn 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 |
Why one Rust binary, SQLite, Git CLI, and shared common-dir state? | |
What do agents publish and when? | |
Which transitions and invariants gate work? | |
Which deterministic rules produce findings and suggestions? | |
How do fingerprints, worktrees, and accepted refs behave? | |
How do Codex, Claude Code, and Cursor discover the skill and MCP server? | |
How do clients configure and call the 18 lifecycle/read tools? | |
Which routes, request bodies, auth, and errors are shipped? | |
What is the machine-readable HTTP contract? | |
How will coordinated and uncoordinated runs be compared? | |
Which generated paths may validation ignore, and why? | |
What is current, next, later, or a non-goal? | |
What does the MVP not guarantee? | |
Which mark, colors, type, icons, and CLI output rules apply to any Foremerge surface? |
Also see the changelog, security policy, and code of conduct.
Links
Website: foremerge.com
Crate: crates.io/crates/foremerge
MCP Registry name: mcp-name: io.github.naw103/foremerge
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 verifyForemerge is licensed under the Apache License 2.0.
Available Tools
18 toolsaccept_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 conflictsARead-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 workADestructive
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 ChangeSetARead-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 intentARead-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 agentsARead-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 workARead-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 statusARead-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
Scored across 18 tools
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.
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.
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.
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
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-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.1MIT
- AlicenseAqualityDmaintenanceA 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.5MIT
- AlicenseNot gradedqualityCmaintenanceAn 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 npm4MIT

STMAofficial
AlicenseNot gradedqualityBmaintenanceAn 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