
foremerge
Agents publish intent and claim semantic scopes before writing code, so two plans that cannot both be true collide in a queryable store instead of in your merge. Local-first, deterministic, Apache-2.0. Requires the foremerge binary on PATH and a repository that has run foremerge init.
- GitHub stars
- 439
Install
/plugin install foremerge@foremergeRun it inside Claude Code after adding the marketplace with /plugin marketplace add naw103/foremerge.
Contents
Discovered from sourceSkills 1
Foremerge
Use Foremerge at semantic engineering boundaries. Git owns files and commit history; Foremerge owns shared intent, advisory claims, dependencies, conflicts, validation evidence, decisions, and provenance across isolated worktrees.
Confirm the integration
Prefer MCP tools when they are available. Use the CLI for setup, diagnostics, event watching, and commands not exposed by the client.
foremerge --json doctor --client all
foremerge --json checks list
Read the answer before going further.
git_repository: falsemeans this directory is not a Git repository, so there is nothing to coordinate. Say so and stop.database_ok: falsewithdatabase_error.codeNOT_INITIALIZEDmeans this repository has never runforemerge init, so it has not opted into coordination. Say so and stop. Do not runinityourself: whether a repository coordinates is the operator's decision, and a store created on your initiative coordinates nothing while looking as though it does.database_ok: falsewith any otherdatabase_errormeans the store exists but cannot be used, for exampleUNSUPPORTED_SCHEMAafter a newer build has migrated it. Report the error andnext_stepto the user and stop. Do not delete, move, or edit the store, and do not runforemerge ledger resetorforemerge ledger migrate: both are one-way decisions for the user. That includesMIGRATION_REQUIRED, where migrating would lock out every client still on an older build.
doctor opens the store read-only: it never creates, initializes or migrates
one, and never writes the ledger itself, though SQLite may make and remove its
own -wal and -shm sidecars while the connection is open. So a false answer
here is trustworthy. A Foremerge tool that answers Foremerge unavailable: ...
is the same situation seen from the MCP server: tell the user the error and its
remedy, leave the store and the MCP configuration alone, and do not assume other
agents can see your work. So is a tool that starts failing mid-session with
UNSUPPORTED_SCHEMA or LEDGER_REPLACED: the ledger changed underneath this
session's server, which stops rather than writing to it.
If the client integration is missing, run the relevant installer from the repository:
foremerge --json setup codex
foremerge --json setup claude
foremerge --json setup cursor
Setup refuses to replace differing skill or MCP entries unless the human explicitly chooses --force. No cloud account or API key is required. The coordination database and named-check registry live under Git's common directory, so linked worktrees share coordination without sharing a working tree.
Coordinate before editing
- Register this agent with its actual model and worktree.
- Query expected scopes for active owners and related work.
- Publish an outcome-oriented intent with semantic scopes and dependencies.
- Inspect returned findings; use
check_conflictsfor a provisional preflight. - Record what you concluded about each
related_workentry withrecord_assessment, before you write code: a verdict ofconflicts,compatible,duplicate, ordepends_on, and the action you will take (proceeding,rescoping,waiting, orabandoning). Work markedowner_stopped_sinceneeds none. - Claim the scopes. Claims are leased advice, never locks.
- Start the claimed work before implementation.
This applies before creating or changing any file meant to land in the
repository, not only code: new files included, build and test output excluded.
Plans, specs, runbooks, and other documents get the same steps, with file:
scopes when nothing more semantic fits. Documents are often rewritten wholesale,
and two overlapping rewrites rarely merge cleanly; when they do, the result can
silently contradict itself.
When you are only planning and not yet writing anything, run check_conflicts
with the plan's summary and the scopes it would declare, operations included. It
stores nothing, and it runs the same comparison as publishing: overlapping
scopes, not only identical ones, and what each plan does to them. query_work
matches a scope exactly, so on its own it can miss related work; use it to read
what is in flight on a scope you already know. Do not publish an intent for a
plan that may never be carried out; publish when you commit to the work or start
writing the plan document itself.
Foremerge only sees agents that coordinate. If a file you have not touched
changes under you and query_work shows no owner for it, tell the user before
you continue, and do not overwrite that change.
Delegated work coordinates too. Before you hand work to a subagent, another session or another worktree, give it its own agent and intent: register and publish for it, or tell it to, and put the agent and intent ids in its instructions. One undeclared participant hides its work from everyone else's publish, so two agents can build the same change at once with neither warned.
Prefer semantic scopes such as symbol:PaymentService, api:/payments, schema:billing.payments, or contract:payments.provider; file scopes are weaker evidence.
Write a method as symbol:Class::method. A dot reads as a namespace separator, so the matching alias of symbol:Class.method is symbol:method: its claims and work queries never meet symbol:Class::method.
A durable cfl_* conflict can be linked to coordinate_with_agent and resolved with resolve_conflict. An eph_* preflight is intentionally not stored: publish/claim first to obtain a durable finding, or send an unlinked message.
CLI equivalent:
foremerge --json agent register --name payments-agent --model MODEL
foremerge --json intent publish --agent AGENT_ID --task add-paypal \
--summary 'Add PayPal support to PaymentService' \
--scope symbol:PaymentService=extend \
--scope contract:payments.provider=extend
foremerge --json assess record --agent-id AGENT_ID --intent-id INTENT_ID \
--related-intent-id RELATED_INTENT_ID --verdict compatible \
--rationale 'Why both plans can be true' --action proceeding
foremerge --json work claim --agent AGENT_ID --intent INTENT_ID \
--scope symbol:PaymentService
foremerge --json work start INTENT_ID --agent AGENT_ID
Publish, verify, and accept
Conflicts are not delivered as push notifications: a later publish by another agent can create a conflict against your intent after your own publish returned conflicts: []. Re-run check_conflicts (CLI: foremerge --json conflicts check --intent-id INTENT_ID) before publishing a ChangeSet and again before requesting verification. start_work and publish_changeset responses also include an open_conflicts snapshot for your intent. Pass an intent id only via intent_id/--intent-id; the free-form intent text field rejects id-shaped input.
Commit a clean candidate with ordinary Git, then:
- Call
publish_changesetwith implementation, dependency, decision, and provenance evidence. Passbase_refwhen you know the true diff base (for example your branch's fork point); otherwise Foremerge derives it from the candidate commit's first parent. - Call
run_verificationwith a configured check name such astest. - Resolve any persisted HIGH conflict you are a party to, only after real agreement with the other party; name the agreeing coordination message in the rationale. Acceptance overrides are operator actions, available on the CLI and the HTTP API and rejected over MCP: ask a human operator instead of overriding yourself.
- Call
accept_changeset; it must match the clean Git commit and passing fingerprint. - Land the accepted commit through ordinary Git or a pull request.
- Call
record_commitwith the actual target-branch integration ref.
Every completed validation is retained. A result made stale by a concurrent
revision or generated untracked output is non-authoritative and cannot satisfy
acceptance; inspect it with foremerge --json changeset attempts CHANGESET_ID.
Only a human/operator may configure validation-exclusions. Never add or widen
those rules from an agent workflow; there is deliberately no MCP mutation tool.
run_verification deliberately accepts a check name, not raw argv. Named checks are trusted local code configured outside the MCP call, for example by a repository maintainer:
foremerge checks set test -- cargo test --all-targets
foremerge checks set lint -- cargo clippy --all-targets -- -D warnings
Do not add or replace named checks unless the user has authorized that repository configuration. If a check you need is not configured, ask a human operator to configure it rather than provisioning it yourself. Checks are repository-scoped: the registry lives under Git's common directory and the commands refuse to run outside a Git repository. Agent-reported tests on publish_changeset are provenance only and never satisfy acceptance.
Acceptance creates refs/foremerge/accepted/<changeset-id>; it does not merge code. Do not call record_commit on the feature-branch HEAD merely because ancestry is reflexive.
Close, abandon, or inspect work
Close every intent before you stop, unless its work is finished and waiting to merge. An intent never closes itself: one left open keeps reading as work in progress and is compared against every later intent on the same scopes. record_commit closes accepted work. Close anything else with discard_work:
- Work that should not land: pass a reason.
- Work that reached Git without passing a named check, so it cannot be accepted (the repository has no check registered, or a human committed it for you): pass
landed_refas well (CLI:--landed REF), naming the commit or branch it landed in. Foremerge refuses a ref that does not contain your published candidate, and records the one that does. The intent still endsDISCARDED: this says where the work went, not that it was verified.
Either way it preserves history, releases claims, and dismisses linked blockers; it does not delete a worktree or reset Git.
Work that is finished but not yet in Git, such as a branch waiting for review, stays open. Publish a ChangeSet for it and name the branch in its summary, so later agents still find it in related_work. If your session ends before it is validated, it is marked owner_stopped_since and records no conflicts below HIGH. Close it when it lands, with record_commit or with discard_work and landed_ref. Discarding it earlier hides it from every later agent while the code still sits on the branch.
publish_intent marks related work whose agent has stopped with owner_stopped_since. That work needs no assessment, and findings below HIGH against it are not recorded as conflicts unless its agent returns. If you are continuing it, take it over with foremerge work adopt instead of duplicating it.
Use query_work for current semantic state, coordinate_with_agent for durable proposals, and these CLI commands when needed:
foremerge --json agent list
foremerge --json intent show INTENT_ID
foremerge --json changeset show CHANGESET_ID
foremerge --json changeset attempts CHANGESET_ID
foremerge --json conflicts detections CONFLICT_ID
foremerge --json coordinate inbox --agent AGENT_ID
foremerge --json events list
foremerge --json events audit
foremerge --json graph
foremerge --json status
foremerge work watch
The corresponding MCP reads are list_agents, get_intent, get_changeset,
and status; prefer them when available.
MCP tools
The complete lifecycle surface is:
register_agent,query_work,publish_intent,check_conflictsclaim_work,start_work,coordinate_with_agent,resolve_conflictpublish_changeset,run_verification,accept_changesetrecord_commit,discard_worklist_agents,get_intent,get_changeset,status
Do not expose the optional HTTP daemon beyond loopback, treat heuristic suggestions as authoritative architecture, accept stale evidence, delete coordination state, or use Foremerge to bypass ordinary Git review and integration.
MCP servers 1
Sponsors
Details
- Marketplace
- naw103/foremerge
- Source
- plugins/foremerge
- Category
- Workflow
- Keywords
- git, coordination, parallel-agents, worktrees, merge-conflicts, mcp