foremerge

foremerge [--json] [--database path] [--cwd path] command [arguments]

foremerge is a local coordination protocol for coding agents working in separate Git worktrees. Each agent publishes what it is about to change, such as a symbol, API, schema, config key, or similar scope, and Foremerge compares those declarations before either side writes code. Git still stores the commits. Foremerge stores the shared plan in SQLite under the repository's Git common directory, so linked worktrees see the same list.The same program is also installed as fmg. Usage and errors use whichever name launched the process. fmg status and foremerge status call the same code.A scope looks like symbol:PaymentService or symbol:PaymentService=replace. Scope kinds are symbol, api, schema, config, infra, test, migration, env, file, component, contract, and domain. Operations are add, extend, modify, replace, remove, rename, and migrate. Only an operation the agent declared can become a HIGH finding. An omitted operation is inferred and stays below that severity.The usual path is intent publish, work claim, work start, then implementation on an isolated branch, changeset publish, changeset validate, changeset accept, ordinary Git integration, and changeset commit. Agent-reported test lines are provenance. Acceptance uses a command Foremerge ran against that candidate's Git fingerprint.foremerge setup wires Codex, Claude Code, and Cursor. foremerge mcp exposes the same lifecycle over stdio, so those clients can call it without the HTTP daemon. The daemon is for harnesses that prefer HTTP. It binds loopback only, and foremerge request will send the bearer token only to a loopback HTTP address.

--json

Print a stable JSON success or error envelope on stdout. This flag is global.

Use this SQLite file instead of the default under Git's common directory. FOREMERGE_DB sets the same path.

Resolve Git and runtime state from path. The default is the current directory.

The default database is <git-common-dir>/foremerge/state.sqlite3. --database and FOREMERGE_DB override it. Agents share awareness only when they open the same file.foremerge init creates that database and a private token file for the API. FOREMERGE_URL (default http://127.0.0.1:47811) tells foremerge request where the daemon is.setup writes skill files and MCP configuration for the selected clients. A skill you edited, or a differing Foremerge MCP entry, is left in place unless you pass --force.Named checks and validation-exclusion rules live in that same private store. validation-exclusions set --path path lists generated, untracked output a validation run may leave behind. Tracked changes are never excludable.

init

Create the shared store under the repository's Git common directory, and a bearer token for the local HTTP API. Tracked files stay untouched.

Install the native skill and MCP entry for one client, or for all three. --skip-mcp writes skills only. --force replaces a Foremerge-managed skill or MCP entry that differs from the one this binary would write.

Check Git, SQLite, shared storage, MCP, and optional client integration.

Show one snapshot of registered agents and their work.

Record an agent. agent list prints id, name, model, worktree, and status.

Announce planned work and return conflicts plus related work. intent show id reads one intent back.

Take an advisory lease on a scope. Overlap warns and still succeeds. work start intent --agent id marks implementation in progress. work query --scope KIND:KEY lists who holds that scope. work watch prints semantic events as they arrive. work discard keeps the audit trail and releases the claim.

Run the deterministic preflight. conflicts list shows persisted findings. conflicts resolve records an agreed outcome.

Store what this agent concluded. Verdicts are conflicts, compatible, duplicate, or depends_on. Actions are proceeding, rescoping, waiting, or abandoning.

Record a candidate linked to the current Git fingerprint. changeset validate id -- command runs that command as Foremerge-owned evidence. changeset accept pins a clean, validated ref at refs/foremerge/accepted/id. changeset commit records the commit that actually landed after ordinary Git integration.

Store a trusted argv check that MCP agents may request by name. checks policy strict|advisory controls acceptance when Foremerge itself verified nothing. checks list and checks remove manage the set.

Create a branch in a new Git worktree. The default base is HEAD.

Append a durable message. coordinate inbox reads one agent's messages.

Serve the JSON API. The default bind is 127.0.0.1:47811. mcp serves the same tools over stdio. request GET|POST path calls the local API with the stored token.

Move the current ledger aside and start empty, or restore a backup. Without --yes it only reports what it would do.

Export the current semantic dependency graph.

Read the append-only event log. events audit checks the hash chain.

Version 0.5.0 of the repository is a pre-1.0, local-first release. Public schemas can still change. The crate published on crates.io can lag the Git repository; a checksum-verified release binary tracks the project's releases.Findings are advisory. A claim warns on overlap and both agents continue. Detection uses fixed rules on the scopes and operations you declared. Two different names for one concept can miss each other, and compatible work can still produce a warning.The store is one SQLite file on the machine that holds the Git common directory. Coordination between machines is outside this version. A network filesystem does not turn that file into a distributed lock service.changeset validate and named checks run as ordinary local processes with your permissions. Passing validation means that recorded command passed for that recorded fingerprint. A later edit makes the attempt non-authoritative. --allow-high-conflicts and --allow-unverified are visible overrides and require --override-reason.

Foremerge was first published in August 2026 (GitHub repository created 2026-08-21, crates.io crate published 2026-08-25). It is written in Rust (rust-version 1.85 in the repository) and released under the Apache License 2.0.

fmg(1), git(1), jq(1), sqlite3(1)

Source code · Homepage · Documentation