Foremerge: a Git like coordination protocol for parallel coding agents. One binary, SQLite, deterministic conflict rules

announcements
1

We open-sourced Foremerge today: a git like coordination for multiple coding agents working one repository, built above Git rather than inside it. It started as an internal tool at GPTree, our AI product.

The Rust bits people here might care about:

  • Single binary: CLI, an axum loopback JSON API, and an MCP server over stdio are all adapters over one rusqlite (bundled) store. No required daemon.

  • Every mutation updates typed SQLite projections, materializes graph edges, and appends a hash-chained semantic event in one transaction.

  • Deterministic conflict rules (for example destructive_vs_additive) over declared semantic scopes and operations (--scope symbol:PaymentService=replace). No model calls in the detection path, so findings are reproducible and explainable.

  • Verification gate: it executes your named check (say cargo test --all-targets) against an exact candidate fingerprint and refuses acceptance if the tree changed since validation.

  • Edition 2024, MSRV 1.85, clap derive, tokio. cargo install foremerge, cargo binstall foremerge, or a checksum-verified install script.

Honest limits: pre-1.0, heuristic detection that can warn on compatible work, local first, benchmark harness exists but no published results yet.

Repo: GitHub - naw103/foremerge: Catch intent conflicts before code conflicts. The open-source coordination protocol for coding agents, built above Git. · GitHub

Protocol feedback is what I am after: is the scope vocabulary (symbol, api, schema, config, migration, contract, ...) the right shape?

4

This is the (unfortunately seemingly) rare case that I see an AI-related project posted here where I can look at its description and at least deduce "well that kind of makes sense and seems to have some value as a tool".[1]

The README is nonetheless a bit too verbose to get a good introduction. (I can't bring myself to actually read all of that in-depth, as it's too hard to be sure how much time went into crafting that text in the first place.)

Similarly, I wouldn't be not sure what context to look through to help answering the question about “scope vocabulary” that you attached to this post.

I see you've made it public on GitHub roughly 1 week ago - I’d be curious for how long it’s been in development and/or in use internally before that.

  1. by contrast, the common cases I've grown to expect is often either:

    • projects over-ambitously reinventing the wheel on something; or
    • over-jargony presentation of things where I'm not sure if I'm just in completely different fields or if it's truly just useless nonesense from the outlook, in its whole premise
    ↩︎
5

Thanks, this is a fair set of points.

On verbosity: agreed. The README grew documentation-first and it shows.

The 30-second version: just paste this into ClaudeCode (or Codex/Cursor) and it just works

Set up Foremerge in this repository so we can coordinate parallel agents.
1. Install it:      curl -fsSL https://foremerge.com/install.sh | sh
2. Initialize:      foremerge init
3. Wire this client and any others in use: foremerge setup all
4. Register the check I should be validated against, for example:
                    foremerge checks set test -- cargo test --all-targets
5. Confirm:         foremerge doctor --client all
Then read the Foremerge skill that step 3 installed for this client and follow
it from now on: publish your intent with semantic scopes before editing, claim
the scope, and check for conflicts before you start.

On where to look for the scope-vocabulary question: docs/conflict-detection.md defines the rules over the vocabulary, and docs/protocol.md defines what agents publish and when. The current kinds are symbol, api, schema, config, infra, test, migration, env, file, component, contract, domain.

We built and started using this tool around Jan this year once GPTree went into beta and its been used since by our team. We run it on our own repositories daily.

6

built above Git rather than inside it

What does that even mean?

(First post, AI-related, AI verbiage, ... :confused:)

7

Fair, Im still trying to figure out how to explain this so that people get it. What I meant is Foremerge does not modify Git or sit in its path. No merge drivers, no hooks required, no changes to your branches, and it never merges, rebases, or pushes anything. Git remains the only source of truth for code.

What it adds is a separate SQLite database stored in the repository's git common directory (next to Git's own files, not in the object store), holding the things Git has no opinion on: declared intents, semantic scopes and operations, claims, conflict findings, and verification results. It reads Git state to fingerprint candidate changes, and on acceptance it records a ref under refs/foremerge/accepted/ so accepted work is durably identifiable. Ordinary git commands neither know nor care that it is there.