Foremerge

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: false means this directory is not a Git repository, so there is nothing to coordinate. Say so and stop.
• database_ok: false with database_error.code NOT_INITIALIZED means this repository has never run foremerge init, so it has not opted into coordination. Say so and stop. Do not run init yourself: 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: false with any other database_error means the store exists but cannot be used, for example UNSUPPORTED_SCHEMA after a newer build has migrated it. Report the error and next_step to the user and stop. Do not delete, move, or edit the store, and do not run foremerge ledger reset: setting a ledger aside is the user's decision.

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

1. Register this agent with its actual model and worktree.
2. Query expected scopes for active owners and related work.
3. Publish an outcome-oriented intent with semantic scopes and dependencies.
4. Inspect returned findings; use check_conflicts for a provisional preflight.
5. Claim the scopes. Claims are leased advice, never locks.
6. 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.

Prefer semantic scopes such as symbol:PaymentService, api:/payments, schema:billing.payments, or contract:payments.provider; file scopes are weaker evidence.

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 work claim --agent AGENT_ID --intent INTENT_ID \
  --scope symbol:PaymentService
foremerge --json work start INTENT_ID --agent AGENT_ID