# Foremerge

> Open-source coordination protocol for coding agents that catches intent conflicts before they become code conflicts, built above Git using a shared SQLite store.

Foremerge is an open-source coordination protocol for coding agents, built above Git and licensed under Apache 2.0. It lets multiple AI agents—Claude Code, Codex, Cursor, or any MCP-capable client—share intent, semantic claims, dependencies, provisional ChangeSets, and verification results through a single SQLite store, so plan collisions surface in a queryable database before any code is written. The project is written in Rust and published on crates.io; version 0.5.0 is the current pre-1.0 release.

## What It Is

Foremerge addresses a gap that Git cannot fill: two agents can each produce individually correct changes in isolated worktrees, yet those changes can silently undo each other when merged. Git compares text and stops on overlapping edits to the same file, but it has no visibility into semantic intent—one agent replacing `PaymentService` while another extends it touches no common lines, so Git merges both without complaint and leaves the second agent's work stranded. Foremerge fixes this by requiring agents to declare what they are about to touch, in semantic terms, before they touch it. Every declaration goes into a shared store; every new declaration is checked against existing ones; conflicts are raised as advisory findings with an explanation and a suggested resolution, before either worktree has changed.

## How the Coordination Protocol Works

The protocol follows a structured lifecycle: `INTENT → CLAIMED → IN_PROGRESS → PROVISIONAL → VALIDATED → ACCEPTED → COMMITTED`. Agents publish intents with typed semantic scopes, claim those scopes as leased advisories, advance through implementation, publish a ChangeSet, and then request Foremerge-executed validation against the exact Git fingerprint of the candidate before acceptance. Key design decisions:

- **No locks, no blocking.** A crashed agent cannot stall the fleet; all conflict findings are advisory.
- **No LLM in the detection path.** Conflict detection is deterministic and rule-based, so the same inputs always produce the same verdict.
- **Semantic scopes, not file paths.** Twelve scope kinds ship in 0.1.0: `symbol`, `api`, `schema`, `config`, `infra`, `test`, `migration`, `env`, `file`, `component`, `contract`, `domain`. This catches API, schema, configuration, infrastructure, and cross-language collisions that file-path diffing misses.
- **Verification-gated acceptance.** Foremerge runs the registered check itself rather than trusting agent-reported test results; agent-reported results are recorded as provenance only.

## Architecture and Deployment Model

Foremerge is a single Rust binary (`foremerge` / `fmg`) that ships three frontends over the same SQLite store: a CLI with `--json` output for scripting, an MCP server over stdio exposing 18 lifecycle and read tools, and an authenticated loopback HTTP daemon with an OpenAPI schema for harnesses that prefer HTTP. The SQLite database lives under the repository's Git common directory, so linked worktrees share it automatically without any additional configuration. The MVP is explicitly local-first and single-machine; multi-machine shared mode is listed on the roadmap but not yet implemented.

## MCP Integration and Mixed-Fleet Support

The 18 MCP tools cover the full agent lifecycle: `register_agent`, `publish_intent`, `record_assessment`, `claim_work`, `query_work`, `check_conflicts`, `publish_changeset`, `coordinate_with_agent`, `start_work`, `resolve_conflict`, `run_verification`, `accept_changeset`, `record_commit`, `discard_work`, `list_agents`, `get_intent`, `get_changeset`, and `status`. The protocol carries nothing provider-specific, so heterogeneous fleets—Claude Code alongside Codex, for example—are the design center. Every ChangeSet records which agent and which model did what, validated how, and against which exact Git fingerprint, producing cross-model coordination provenance. The MCP registry name is `io.github.naw103/foremerge`.

## Update: v0.5.0

The latest release is v0.5.0, published on 2026-09-23. The repository was created in August 2026 and has seen active development through September 2026. The README notes that the CLI, JSON API, MCP server, SQLite store, deterministic conflict detector, and verification-gated lifecycle are all implemented in this pre-1.0 MVP. Public schemas may still change, and published benchmark results comparing coordinated versus uncoordinated runs do not yet exist. The `fmg` short alias for the binary ships from 0.4.0 onward. The project explicitly documents its limitations: conflict detection is heuristic and can miss synonymous concepts or warn on compatible work, and the loopback bearer token is not a public deployment security model.

## Features
- Intent conflict detection before code conflicts
- Semantic scope declarations (symbol, api, schema, config, infra, test, migration, env, file, component, contract, domain)
- Shared SQLite coordination store in Git common directory
- 18 MCP lifecycle and read tools over stdio
- CLI with --json output for scripting
- Authenticated loopback HTTP daemon with OpenAPI schema
- Verification-gated ChangeSet acceptance
- Deterministic, rule-based conflict detection (no LLM in detection path)
- Advisory-only claims — no file locks or agent blocking
- Cross-model provenance recording (agent, model, fingerprint)
- Git worktree isolation with shared awareness
- Hash-chained semantic event log
- Validation exclusion rules for generated output
- foremerge setup for Claude Code, Codex, and Cursor
- Native skill installation for agent clients
- Preflight conflict checking before implementation
- Leased advisory scope claims
- Loopback JSON API with bearer token auth

## Integrations
Claude Code, Codex, Cursor, Git, MCP (Model Context Protocol), crates.io, SQLite, Rust cargo

## Platforms
CLI, API, MACOS, LINUX, WINDOWS

## Pricing
Open Source

## Version
0.5.0

## Links
- Website: https://foremerge.com
- Documentation: https://github.com/naw103/foremerge/tree/main/docs
- Repository: https://github.com/naw103/foremerge
- EveryDev.ai: https://www.everydev.ai/tools/foremerge