Show HN: Foremerge – Catch intent conflicts between parallel coding agents

What it claims

Foremerge is a local-first coordination protocol (v0.5.0, pre-1.0 MVP) sitting above Git that catches intent conflicts between parallel coding agents before they write code. Its core mechanism: agents declare a semantic scope and operation ("symbol:PaymentService=replace" vs "symbol:PaymentService=extend") up front; a deterministic detector compares declarations and raises an advisory (e.g. HIGH) with an explanation and suggestion. The canonical example — one agent replacing PaymentService, another extending it in a different file — is exactly the case Git merges cleanly because no text overlaps, leaving one agent's work stranded.

How it works

Two hard design choices distinguish it from what the summary implies:

• Never locks, never blocks. Claims are leased advisories, not exclusive ownership; both claims on the same scope succeed, the second just gets an overlap warning. Rationale given: a crashed agent shouldn't stall the fleet.
• No model in the loop. Conflict detection is deterministic (not LLM-judged), so identical inputs always yield the same verdict, and differently-phrased plans reach the same result because the declared operation is compared, not prose.

State lives in <git-common-dir>/foremerge/state.sqlite3 — SQLite projections plus a hash-chained event log, shared across linked worktrees on one machine. Frontends are a CLI, JSON API, and MCP server over the same store. Scope kinds: symbol api schema config infra test migration env file component contract domain.

Acceptance is verification-gated: Foremerge runs the registered check itself (recording argv, exit, output, fingerprint) rather than trusting an agent's self-reported test. Any change after validation invalidates the attempt. Acceptance requires a clean worktree and no unresolved HIGH conflict (overridable only via explicit --allow-high-conflicts --override-reason), and creates a ref — it does not merge, rebase, push, or touch tracked files.

flowchart LR
  A[Agent declares intent + scope] --> D{Declarations overlap?}
  D -->|conflict| W[HIGH advisory + suggestion, both trees still clean]
  D -->|clear| C[claim → work → ChangeSet]
  C --> V{Foremerge-run validation passes at fingerprint?}
  V -->|yes, no HIGH| ACC[accept → ref]
  V -->|no| BLOCK[not accepted / UNVERIFIED]
  ACC --> G[you integrate with ordinary Git]

How to use it

Prebuilt checksum-verified binary (macOS/Linux, installs to ~/.local/bin; Windows on releases page):

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

Or cargo install --locked --git https://github.com/naw103/foremerge foremerge (Rust 1.85+). Wire clients and gate:

foremerge setup all
foremerge checks set test -- cargo test --all-targets
foremerge doctor --client all

fmg is the same binary under a shorter name. Ships native skills + MCP entries for Claude Code, Codex, Cursor. Optional authenticated loopback daemon on http://127.0.0.1:47811 (bearer token). Apache 2.0. Crate on crates.io; MCP name io.github.naw103/foremerge.

Limits

Stated plainly by the authors:

• No published benchmark results yet — only fixtures and a plan; coordinated-vs-uncoordinated performance is unproven.
• Single machine only. SQLite is not replicated; do not infer distributed safety from a network-mounted DB. Cross-machine coordination is out of scope.
• Detection is deterministic but heuristic — misses synonymous concepts, can warn on compatible work.
• Validation commands run as trusted local code, unsandboxed, with your OS permissions.
• Public schemas may still change (pre-1.0). Passing validation proves only the recorded command passed, not that the test plan was complete. Does not replace code review, CI, security scanning, or backups.