Foremerge
Catch intent conflicts before code conflicts — the open-source coordination protocol for coding agents, built above Git.
- Source repo
- naw103/foremerge
- Stars
- ★ 519
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 77/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A team runs multiple Claude Code, Codex, or Cursor agents in parallel on the same repo and wants semantic conflicts surfaced before code is written, not at merge time.
- Not a fit if
- Teams needing cross-machine coordination: the MVP does not replicate SQLite
- Teams wanting hard locks or blocking gates: findings are advisory only
- Small teams or solo repos unwilling to run per-agent intent ceremony
- Source review
- 77/100 · Good
What does this agent do, and when should you use it?
Foremerge is an open-source coordination protocol for coding agents, shipped as a single Rust binary that runs above Git. Its core idea is that parallel agents announce what they intend to do before writing code. Through three frontends — a CLI, an MCP server over stdio, and an authenticated loopback JSON API — it stores intents, semantic scopes, dependencies, provisional ChangeSets, decisions, and provenance in a SQLite database inside the repository's Git common directory, so agents in isolated worktrees on the same machine share one coordination picture. Conflict detection is deterministic: identical inputs always produce identical verdicts, no model is asked to judge, and findings are explainable advisories rather than locks. Claims are leased, advisory-only warnings that never block files or agents, while acceptance is gated by verification Foremerge runs itself rather than taking an agent's word. Version 0.4.0 is a local-first pre-1.0 MVP; shared multi-machine mode and published benchmark results do not yet exist.
The flow works like this: foremerge init creates coordination state (state.sqlite3) under the repo's Git common directory; foremerge agent register records agent, model, and worktree provenance; foremerge intent publish --scope symbol:PaymentService=replace announces an intent and declares an operation per semantic scope. Scope kinds include symbol, api, schema, config, infra, test, migration, env, file, component, contract, and domain. At publish time, the deterministic conflict detector compares declarations immediately — e.g., one agent declaring replace on symbol:PaymentService while another declares extend yields a HIGH destructive_vs_additive finding with an explanation and a suggestion (such as coordinating on a PaymentProvider abstraction). You then use work claim for advisory leases, work start to move into implementation, work query to see who is changing what, conflicts check to preflight plans, and coordinate send for durable messages. When done, changeset publish records the implementation, fingerprint, and Git provenance; changeset validate runs a trusted check Foremerge owns, recording the argv, exit status, output, duration, and fingerprint; changeset accept applies conflict, dependency, validation, and Git gates (creating refs/foremerge/accepted/<changeset-id> without merging code); changeset commit records the integration commit that actually landed. foremerge setup claude/codex/cursor installs a native skill and registers an MCP server per client (foremerge mcp, exposing 18 lifecycle tools), and foremerge daemon serves a bearer-token-protected loopback JSON API. A Cloud connector syncs verified agent.registered and intent.published events (with Ed25519 snapshot verification and keyring-stored credentials) without changing the standalone workflow.
- A team runs multiple Claude Code, Codex, or Cursor agents in parallel on the same repo and wants semantic conflicts surfaced before code is written, not at merge time.
- One agent migrates callers to a new StripePaymentService while another adds PayPal support to the old PaymentService — no file overlap, Git merges silently, but the work cancels out; Foremerge raises a HIGH advisory before either worktree changes.
- A maintainer wants the acceptance gate to run a repository-defined executable check (e.g.,
cargo test --all-targets) rather than trusting agent-reported test prose. - Teams using Git worktrees to give each agent an isolated file copy want all worktrees to share one coordination state (stored by default in the Git common directory).
- Teams that need an audit trail of who decided what about which symbol rely on the hash-chained event log and the UNVERIFIED recording mechanism.
- CI or hosted environments use the Cloud connector via
env:FOREMERGE_CLOUD_TOKENto sync verified registration and intent events.
How do you install or deploy this agent?
Install a prebuilt, checksum-verified release binary (macOS and Linux; installs to ~/.local/bin and provides both foremerge and fmg): curl -fsSL https://foremerge.com/install.sh | sh. Windows binaries are on the releases page. Or build from source (Rust 1.85+ required): cargo install --locked --git https://github.com/naw103/foremerge foremerge. The manual path also needs Git and jq. Then initialize and self-check: foremerge init, then foremerge doctor.
How do you use this agent?
The fastest path is pasting one instruction block into Claude Code, Codex, or Cursor, which will: install Foremerge, run foremerge init, run foremerge setup all (installs the native skill and enables MCP; the client prompts first), register a check such as foremerge checks set test -- cargo test --all-targets (replace with your repo's real check), and confirm with foremerge doctor --client all. From then on, follow the installed skill: publish intent with semantic scopes before editing, claim the scope, and check for conflicts before starting. Manual flow: foremerge -- agent register --name stripe-agent --no-worktree to register; foremerge -- intent publish --agent <ID> --task modernize-payments --summary "..." --scope symbol:PaymentService=replace to publish and immediately receive conflicts plus related_work; foremerge work claim to lease a scope; foremerge status to see all agents. For cloud features, foremerge cloud login --base-url https://cloud.foremerge.com (credentials go to the OS keyring), then cloud link and cloud sync.
What are this agent's strengths and limitations?
- Deterministic conflict detection: based on declared operations rather than reading natural-language summaries — 'Consolidate payments onto Stripe' and 'Replace PaymentService with Stripe' reach the same verdict, with no model in the loop.
- Detection happens before code is written, so both worktrees are still clean and no work is thrown away; advisories name the agents, explain the clash, and suggest a split.
- The verification gate is Foremerge-owned: it executes the registered check and records argv, exit status, output, duration, and candidate fingerprint; agent-reported test results count as provenance only, and any post-validation change makes the attempt non-authoritative.
- Local-first architecture: state lives in SQLite under the Git common directory without touching tracked files; a hash-chained event log gives tamper evidence; advisory claims mean a crashed agent cannot stall the fleet.
- It is a pre-1.0 MVP (0.4.0) with public schemas that may still change; no cross-machine shared mode, and no distributed safety can be inferred from a network-mounted database.
- Detection is heuristic: it can miss synonymous concepts and warn on compatible work, and it only helps if the team maintains the discipline of publishing intents.
- Validation commands run as trusted local code with full OS permissions — Foremerge does not sandbox them — and the JSON API is loopback-only, not a hardened multi-tenant service.
- No published coordinated-vs-uncoordinated benchmark results yet; executable fixtures and a benchmark plan exist, but the evidence is not public.
- It adds a per-agent ceremony (register, publish, claim, ChangeSet, validate, accept, record commit) that is a real adoption cost for small teams or single-developer repos.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Foremerge This agent | 77 · Good | CLIFree | ★ 519 | today | Rust | Codex · Claude Code |
| Loop Engineering | 69 · Some gaps | CLIFree + model costs | ★ 12k | 1d ago | TypeScript | Codex · Claude Code |
| Concord MCP | 67 · Some gaps | — | ★ 663 | 2d ago | TypeScript | Codex · Claude Code |
| zerostack | 57 · Major gaps | CLIFree + model costs | ★ 1.7k | 2d ago | Rust | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege and confirmation are evidenced: MCP cannot change exclusion policy, publishing requires an approval-gated environment, setup never overwrites edited skill files without --force; deducted because validation commands run with full user permissions and are explicitly unsandboxed. Data-flow transparency is strong (envelope fields, status fields, token-exclusion claims). Sensitive-data handling is thoroughly described (OS keyring, no plaintext fallback) but unverified statically. Dependencies are recent with rustls, yet no audit/lock evidence. Rollback/revocation paths (cloud logout/unlink) are well described but not executable here. Source attribution relies on self-reported agent register --model.
Version 0.4.0 is consistent across README, Cargo.toml, and CI; internal self-consistency is high, but source code was not shown, so error-handling quality cannot be confirmed. Dependencies are well-known crates and --locked installs are reproducible; failure paths (CLOUD_MUTATION_DEGRADED, doctor checks) are documented but their implementation is not visible.
Multi-client (Claude Code/Codex/Cursor) and multi-platform (macOS/Linux/Windows) scenarios are well covered; capability boundaries (pre-1.0, single machine, no distributed safety) are explicit. Trigger precision depends on agents voluntarily publishing intents — convention, not enforcement; environment misuse like network-mounted databases is warned about, but default behavior fits only ordinary local setups.
Information architecture is clear (How it works / Quickstart / Cloud / ChangeSets); install notes cover installer, cargo, Windows, updates, and fmg collision handling; LICENSE is complete Apache-2.0; limitations and SECURITY.md state known constraints. Deductions: README is truncated in evidence, no CHANGELOG file visible, maintenance is a single individual repo (naw103) with 'best effort' support and a seven-day target but no team or funding evidence; examples are rich but no FAQ, and naming stability is argued in comments rather than shown in history.
Output usability is supported by the JSON API, jq-friendly fields, and structured conflict explanations; marginal value is high — semantic conflicts Git cannot see are a real gap, and the deterministic, non-LLM design is a clear stance. Cost-benefit is moderate: adopting a new protocol, validation gate, and state store burdens solo or small teams, and MVP-stage benefit cannot be proven statically.
Claims are mostly traceable to concrete commands, field names, ADR references, and example transcripts; fact/inference separation is good (explicit about what the hash chain does not provide, and how demo images were produced). Deductions: 'real terminal recording' and 'checksum-verified' claims cannot be independently confirmed statically; cross-source corroboration is limited to internal document consistency, with no independent evaluation or third-party references visible.
- Validation commands run with full invoking-user permissions and are not sandboxed; only register check commands you fully trust.
- Pre-1.0 software: public schemas may change; single-machine SQLite provides no distributed safety — do not infer it from a network-mounted database.
- The README asks an agent to run curl | sh; review the install script manually before executing.
- MCP being unable to modify validation policy is not a security boundary; any local user who can write the Git common directory can change executable policy.
- Maintenance is an individual repository with best-effort security response, not a service-level guarantee.
- This is a static review; no commands or tests were executed, and demo images / 'real recording' claims are not independently verified.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.5.1 Foremerge v0.5.1
Release notes excerpt
A patch release, compatible with 0.5.0. The ledger schema is unchanged, so the two read the same coordination store. It fixes doctor on Windows and for anyone who ran setup as fmg, keeps foremerge mcp answering when it starts outside a repository, and adds npm as an install channel. Changed - foremerge mcp started outside a Git repository, without --database, no longer exits before the handshake. It answers initialize and tools/list as an unavailable server does: the instructions begin Foremerge unavailable: NOT_A_REPOSITORY:, and every tool call returns …View on GitHub ↗ -
v0.5.0 Foremerge v0.5.0
Release notes excerpt
This is a minor version because it breaks one HTTP endpoint's request body. The ledger schema is unchanged, so 0.4.x builds and this one read the same coordination store, and the CLI and MCP surfaces are unchanged. Changed - Breaking (HTTP API): POST /v1/changesets/{id}/validate now runs a check by name from the repository's trusted registry, the same one MCP's run_verification uses, instead of executing an argument vector taken from the request body. The body is {"check": "<name>"}, and the check runs in the ChangeSet's recorded worktree. A body carrying command, …View on GitHub ↗ -
v0.4.3 Foremerge v0.4.3
Release notes excerpt
What's Changed * Add the community-raised launch-week items to the roadmap by @naw103 in https://github.com/naw103/foremerge/pull/25 * Send structuredContent only for object results by @naw103 in https://github.com/naw103/foremerge/pull/28 * Scope the roadmap to what this repository will do by @naw103 in https://github.com/naw103/foremerge/pull/29 * Document every MCP tool parameter and when to use each tool by @naw103 in https://github.com/naw103/foremerge/pull/26 * Release 0.4.3: make a ledger migration survivable by @naw103 in https://github.com/naw103/foremerge/pull/30 …View on GitHub ↗