Foremerge: an open-source Git-level protocol for coding agents to declare intent before writing code

The developer behind Foremerge has answered thirty-one reader questions about the project in a dev.to post, offering a detailed look at an open-source coordination protocol built to keep parallel coding agents from undermining each other. The questions came from a reader, Vedant Madane, who worked through the code and raised them in a GitHub discussion; the author answered every one there and has now republished the exchange with light edits, plus three questions answered for the first time.

What Foremerge is

According to the post, Foremerge is a coordination layer that sits above Git. It ships as a single Rust binary under an Apache-2.0 licence, is local-first, and exposes a CLI, a local JSON API and an MCP server, all backed by one SQLite database stored in the repository's Git common directory. Before writing code, an agent publishes intent and claims a semantic scope, tagging it with a declared operation from a versioned vocabulary of seven: add, extend, modify, replace, remove, rename and migrate. When two plans cannot both be true, the conflict is caught in the shared store instead of at merge time.

Placing the database in the Git common directory is deliberate: it is the one location every worktree of a repository already shares, so worktree isolation plus shared coordination state arrives with no extra infrastructure.

The failure behind it

The author traces the tool to a specific incident. One agent was replacing a payment service class while a second, working a backlog ticket, extended the same class with an additional provider. The changes sat in different worktrees, shared no overlapping lines and merged cleanly, yet the second depended on an extension point the first had deleted. Review caught the problem and CI would have flagged it too, but the author argues that without solid tests such a break can reach production. The cleanup cost a day of refactoring. After running an internal version of the tool, the author extracted it from an internal tools monorepo and open-sourced it in late August.

Why intent comes before code

Asked why the protocol relies on declared intent rather than post-hoc analysis of pull requests, the author points to timing and cost: diff-based detection finds a collision only after both agents have spent their tokens, when the best option left is discarding or refactoring the work. A declared operation is also a fact, while an operation inferred from a diff is a guess. In version 0.4.0, only declared operations can assert HIGH-severity findings; matches inferred from prose are capped below HIGH, because a coordination layer that guesses wrong at high severity quickly loses its users' trust.

Advisory, deterministic, local

The tool warns but never locks. A lock assumes the declaring agent is right and will finish, and agents abandon work constantly, so one stale lock could gridlock a fleet. The author also notes that a semantic lock cannot be enforced without intercepting filesystem writes, which the tool deliberately avoids. Enforcement instead happens at acceptance: accepting a ChangeSet requires no unresolved HIGH findings plus verification against the exact candidate fingerprint, and the ledger records overrides, so ignoring a warning becomes a visible decision rather than a silent one.

The conflict detector is deterministic, with no LLM judge, because the detector is the trust core and must be reproducible, testable, free, offline and identical for every user. Pure rules struggle when meaning rather than exact text matters, covering synonyms, undeclared renames and cross-file contract drift, so fuzzier matching will only ever propose findings below HIGH. CRDTs were ruled out because they are built to make concurrent edits converge and conflicts vanish, whereas Foremerge's whole job is surfacing incompatibilities. Git notes were rejected as poorly queryable. Hard locks, a merge queue and editor-buffer sync all sit on the non-goals list, each of which would claim an authority the tool cannot actually hold.

Roadmap and open questions

The primary users today are solo developers running two or more agents on one machine; the author says fleet-scale use still needs validation. Version 1.0 is meant to promise protocol stability, backed by coordinated-versus-uncoordinated benchmarks with raw data, versioned JSON Schemas for the protocol surface, at least one language adapter so symbol scopes resolve structurally rather than as strings, and calibration evidence linking findings to real conflicts. Version 0.4.1 adds an as_of sequence so clients can tell how stale an empty conflict result is, and drift detection between what was declared and what is actually edited is planned for 0.5.0. The author also concedes that real-world compliance, meaning how often agents actually publish intent, is unknown beyond the team's own use, and is something the project wants traces for.

Why it matters

Running several coding agents in parallel worktrees is becoming routine, and Git's line-level model does not notice when two clean merges are semantically incompatible. Foremerge targets exactly that gap between textual and semantic conflict, and its choices of advisory warnings, deterministic detection and local-first storage form a considered position on what a coordination layer can legitimately enforce. The 1.0 criteria are notably restrained, treating benchmarks and calibration evidence as prerequisites for a stability promise rather than marketing extras. For teams experimenting with multi-agent workflows over MCP, this is a project worth watching, and the Q&A format makes its reasoning unusually accessible.