Foremerge: catching intent conflicts before coding agents merge

The conflict Git is structurally unable to see

Git compares text. When two agents edit the same lines of the same file, it stops you. The case Foremerge targets is the one where nothing overlaps. The README's example is concrete: one agent replaces `PaymentService` with `StripePaymentService`, another adds PayPal support to `PaymentService`. The edits land in different files, so Git merges both without complaint, and the PayPal work is left attached to a class nothing calls any more.

That is a genuine gap, not a marketing one. A text merge tool cannot detect that one change removed an extension point another change depends on, because the dependency is semantic and the diff is not. Foremerge's answer is to move the comparison earlier, to the point where agents announce targets rather than diffs. The project is aimed at teams already running Claude Code, Codex, or Cursor in parallel worktrees, where each agent has an isolated copy of the code and therefore no natural moment to notice the others.

Declared scopes, a SQLite store inside .git, and a deterministic verdict

The mechanism has three parts. An agent publishes what it is about to touch as a semantic scope, such as `symbol:PaymentService`, together with an operation. The README's example shows one agent declaring `replace` and another declaring `extend` on the same scope. Those declarations go into a small database inside the project's `.git` folder, which is what gives every agent on the machine the same view regardless of which client it is.

When two declarations collide, Foremerge raises a `HIGH` advisory, names the two agents, explains the clash, and suggests coordinating on a stable abstraction such as `PaymentProvider`. The README is careful about what that suggestion is: explainable evidence, not an automatic architecture decision. Because the operation is declared rather than inferred from a plan summary, the phrasing does not matter. "Consolidate payments onto Stripe" and "Replace PaymentService with Stripe" reach the same verdict.

Two design choices are worth stating plainly. Foremerge never locks a file or blocks an agent, on the stated grounds that a single crashed agent would stall the whole fleet. And it never asks a model to judge conflicts, so the same inputs always produce the same answer. Both choices trade enforcement for availability and reproducibility. If you want a hard gate, this is not one.

Installing Foremerge and reaching a first conflict

The README offers two paths. The agent path is a block of text you paste into Claude Code, Codex, or Cursor from inside the repository you want to coordinate; it installs Foremerge, runs `foremerge init`, wires the clients with `foremerge setup all`, registers a validation check, and confirms with `foremerge doctor --client all`. Step 3 asks the client to enable an MCP server, so the client prompts before doing so. The Codex registration is user level, but one registration serves every repository, so start Codex inside the repository you want coordinated.

The manual path needs a recent Git and `jq`. The installer fetches a prebuilt, checksum-verified release binary for macOS and Linux and places it in `~/.local/bin`:

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

This installs two names for the same program, `foremerge` and `fmg`, so `fmg status` and `foremerge status` do the same thing. From 0.4.0 onward the installer, the release archives, and `cargo install` all carry both names. If something else on your PATH already answers to `fmg`, the README says the installer leaves it alone.

Building from source requires Rust 1.85 or newer. The README gives two forms:

cargo install --locked --git https://github.com/naw103/foremerge foremerge

Or, from a checkout, `cargo install --locked --path .`. Windows binaries are on the releases page. To update, re-run the installer.

Inside the repository you want to coordinate, initialization and a health check are two commands:

foremerge init
foremerge doctor

`foremerge init` creates the store inside `.git`; `foremerge doctor` reports whether the installation and client wiring are healthy. After that, register the command an agent's work should be validated against. The README's example is:

foremerge checks set test -- cargo test --all-targets

Replace the command with your repository's real test command. That check is what the verification-gated lifecycle runs against provisional ChangeSets, so a wrong command here weakens the part of the system that is supposed to gate work.

What 0.4.1 is not, and where it will mislead you

The README states the status directly: Foremerge 0.4.1 is a pre-1.0, local-first MVP, and public schemas may still change. Two absences matter more than the version number. Shared multi-machine mode does not yet exist, so the shared list of declarations is shared across agents on your machine, not across your team. If your agents run on separate hosts or in separate CI runners, the coordination picture is not there.

The second is that the warnings are advisory by design. Foremerge will tell you two agents are about to collide; it will not stop them. A team that wants an enforced gate on scope changes has to build that enforcement itself, on top of the advisory. There is also no model in the conflict path, which is a strength for reproducibility and a limit for nuance: the detector compares declared scopes and operations, so an agent that declares a vague or wrong scope gets a vague or wrong verdict. The quality of the output depends on the discipline of the publishers.

Finally, the repository has a benchmarks directory and a `query_benchmark` example, and the Makefile exposes `make benchmarks` and `make query-benchmark`. The README states that published benchmark results do not yet exist. Treat the harness as a harness, not as evidence about how the detector behaves at your scale.

How Foremerge differs from a merge queue or a lock server

The closest familiar alternative is a merge queue, as implemented by GitHub or by tools like Bors and Mergify. A merge queue serializes integration: it takes finished branches, rebases and tests them one at a time, and rejects the ones that fail. It operates after the work exists. Foremerge operates before, on declared intent, and its output is an advisory naming two agents and the reason their plans clash. A merge queue would have caught the PaymentService case only if a test happened to exercise the stranded PayPal path; Foremerge flags it while both worktrees are still clean, which is the point the README makes about no work having to be thrown away.

The other near neighbour is a lock server or a file-claim system, the kind of thing built on top of a shared filesystem or a database. Those enforce mutual exclusion: hold the lock, or wait. Foremerge's README says it deliberately does not do that, because a crashed agent holding a lock stalls everything else. That is a real difference in failure mode, not a detail. A lock server gives you a guarantee and a new way to deadlock; Foremerge gives you a warning and no new way to block. If your problem is two agents writing the same file, Git already handles it. If your problem is agents undoing each other's design decisions across files, the advisory model is the relevant one.

Licence, build cost, and what upgrading involves

Foremerge is Apache-2.0, and the Cargo manifest carries `license = "Apache-2.0"`. Apache-2.0 includes an express patent grant and requires that you preserve notices and state changes; it is permissive, so it does not oblige you to open your own code. This is a description of the licence text, not legal advice, and if you redistribute a modified binary you should read the licence yourself.

The upgrade cost is low in the ordinary case. The README says to update by re-running the installer, and `cargo install --locked --git https://github.com/naw103/foremerge foremerge` pins the dependency graph for source builds. The real cost sits elsewhere: the README warns that public schemas may still change before 1.0, and the project moved from 0.3.1 to 0.4.0 to 0.4.1 within roughly three weeks, with the dual `foremerge`/`fmg` binary naming arriving in 0.4.0. A pre-1.0 project with changing schemas means any tooling you write against the JSON API or the SQLite store may need attention on upgrade. The CLI and MCP surfaces are the stabler bet.

On the development side, the Makefile sets `MSRV ?= 1.85.0` and exposes `make msrv`, which installs the pinned toolchain and runs clippy and tests against it. That is the version CI is built around, so it is the version to match if you vendor the crate.

Editorial conclusion

Adopt Foremerge if you already run two or more coding agents in parallel worktrees on one machine and you want to see scope collisions before either agent writes code. Do not adopt it if you need cross-machine coordination or hard file locks: the README states that shared multi-machine mode does not yet exist, and that Foremerge deliberately never locks a file or blocks an agent. Before trusting it, verify one thing first: that `foremerge checks set test -- cargo test --all-targets` matches your repository's real test command, because the verification-gated lifecycle depends on it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. naw103/foremerge on GitHub
3. Project website
4. README
5. Releases