Foremerge is the open-source coordination protocol for coding agents, built above Git. Agents keep secluded worktrees during sharing intent, semantic claims, dependencies, provisional ChangeSets, decisions, validation, and provenance.
| Tell your delegate to install | → | Done | → | See collisions before they land |
|---|---|---|---|---|
| Paste one row into Claude Code, Codex, or Cursor | It installs Foremerge and wires itself up | Every delegate sees what the others are concerning to change, equal in distinct worktrees |
Status: Foremerge 0.5.0 is a pre-1.0, local-first MVP. The CLI, JSON API, MCP server, SQLite store, deterministic battle detector, and verification-gated lifecycle are implemented. Public schemas may still change. Published benchmark results do not yet exist, and coordination between machines is exterior this project's scope.
Say you have two AI agents operating on the identical project at the identical time. Each one gets its own copy of the code, so they never combat complete files. Both finish. Both appearance correct. Then you discover they undid all other's work.
Git cannot notify you concerning that, since Git compares content and not intent. It will halt you whenever two agents edit the identical part of the identical file. What it cannot see is two edits that are all absolutely sensible on their own and land in distinct files. If one delegate moves all visitant onto a new StripePaymentService during another adds PayPal assistance to the old PaymentService, nothing overlaps, so Git merges the two without grievance and the PayPal activity is remaining stranded on a category nothing calls any more.
Foremerge fixes this by having agents province what they are concerning to do, before they do it.
- Each delegate says what it is concerning to touch. Not the code, fair the target, akin "I am going to alter the sendEmail function."
- Every delegate says from one shared list. It is a small repository inside your project's .git folder, so all delegate on your device sees the same picture, whether it is Claude, Codex, or Cursor.
- If two plans collide, you comprehend concerning it correct away. Foremerge names the two agents, explains why their plans clash, and suggests how to divided the work. Both worktrees are motionless spotless at that point, so no activity has to be thrown away.
Think of it as a shared whiteboard. Before an delegate starts, it writes downward what it is concerning to activity on, and it says what everyone alternatively already wrote.
Two things Foremerge deliberately does not do. It never locks a document or blocks an agent, since a sole wrecked delegate would afterward stall the entire fleet, so the warnings are advisory and you remain in charge. And it never asks a example to judge conflicts, so the identical inputs continually create the identical answer.
Agent A: Replace PaymentService alongside StripePaymentService Agent B: Add PayPal assistance to PaymentService These agents can activity in distinct trees without touching the identical line. The plans motionless collide: one removes the expansion item during the another depends on it.
Both agents province the identical symbol:PaymentService scope, one saying it will replace it and the another that it volition broaden it. Foremerge compares those two declarations before either writes code, raises a HIGH advisory, and suggests coordinating on a stable idea specified as PaymentProvider. That suggestion is explainable evidence, not an automatic architecture decision or a hard lock.
Because the procedure is declared fairly than peruse out of the summary, it does not matter how either delegate phrased its plan. "Consolidate payments onto Stripe" and "Replace PaymentService alongside Stripe" attain the identical verdict.
Git remains the durable repository. Foremerge supplies the missing shared awareness complete it.
Rendered from the genuine battle sectors captured by the 0.1.0 release-binary run in examples/terminal-session.txt. The displayed command uses the shown jq filter; output is abridged for readability.
Paste this into Claude Code, Codex, or Cursor from inner the repository you want to coordinate:
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 inspect I have to be validated against, for example: foremerge checks set test -- cargo test --all-targets 5. Confirm: foremerge doctor --client all Then peruse the Foremerge accomplishment that stage 3 installed for this client and follow it from now on: publish your intent alongside semantic scopes before editing, claim the scope, and inspect for conflicts before you start. Adjust stage 4 to any this repository's genuine test command is. Step 3 asks the client to allow an MCP server, so it volition immediate you before doing so. The Codex registration is person level, but one registration serves all repository: start Codex inner the repository you desire it to coordinate.
You need a latest Git and jq. Install a prebuilt, checksum-verified release binary (macOS and Linux; the manuscript installs to ~/.local/bin):
curl -fsSL https://foremerge.com/install.sh | shTip
Two commands, one program. This installs foremerge and fmg, the same binary under a shorter name, so fmg position and foremerge position do the same thing. Examples below enchantment out foremerge; category whichever you prefer.
Or build from origin alongside Rust 1.85+: cargo instal --locked --git https://github.com/naw103/foremerge foremerge, or cargo instal --locked --path . from a checkout. Windows binaries are on the releases page. To update, upgrade the identical way you installed, afterward re-run foremerge setup and restart your delegate clients; Upgrading Foremerge explains why all stage matters. Then, inner the repository you desire to coordinate:
foremerge init foremerge doctor
The installer, the publish archives and cargo instal all transport the two names from 0.4.0 onward. If item alternatively on your PATH already answers to fmg, the installer leaves it solitary and says so fairly than shadowing it.
Install the native accomplishment and MCP admission for any clients used in this repository, then define the trusted checks agents may petition by name:
foremerge setup all foremerge checks set test -- cargo test --all-targets foremerge doctor --client all
Acceptance is verification-gated: Foremerge runs the inspect itself fairly than taking an agent's term for it. Pick a inspect that is accelerated and that would actually catch a damaged handoff, specified as a build or a typecheck, fairly than a complete CI suite; this entrance decides whether another agents may treat the activity as done, and it does not substitute CI. If this repository has nothing meaningful to verify, say so once fairly than registering a inspect that continually passes:
foremerge checks guideline advisory
Work accepted that way is recorded as UNVERIFIED alongside the reason, so the audit trail never implies a inspect ran whenever none did. foremerge doctor reports whether the registered checks can really run here, which matters in agent worktrees, since dependency directories are normally gitignored and git worktree add volition not create them.
Use setup codex, setup claude, or setup cursor for one client. Setup preserves unrelated configuration (including key command in project MCP JSON). Upgrading Foremerge refreshes its own unedited accomplishment document in place, but a skill file you edited, or a differing Foremerge MCP entry, is never replaced unless you explicitly continue --force. setup all attempts all client and reports each result, exiting nonzero if any failed. The Codex MCP registration is user-level and serves all repository, resolved from the directory Codex is started in; see agent client setup.
init creates local coordination province under the repository's Git common directory. It does not alter tracked files. The following no-worktree sessions are adequate to exercise pre-code detection; genuine coding agents should register their secluded worktrees and genuine example identifiers.
STRIPE_AGENT=$( foremerge --json delegate enroll \ --name stripe-agent \ --no-worktree | jq -er '.data.id' ) STRIPE_RESULT=$( foremerge --json intent publish \ --agent "$STRIPE_AGENT" \ --task "modernize-payments" \ --summary "Replace PaymentService alongside StripePaymentService" \ --scope symbol:PaymentService=replace ) STRIPE_INTENT=$(printf '%s\n' "$STRIPE_RESULT" | jq -er '.data.intent.id') PAYPAL_AGENT=$( foremerge --json delegate enroll \ --name paypal-agent \ --no-worktree | jq -er '.data.id' ) PAYPAL_RESULT=$( foremerge --json intent publish \ --agent "$PAYPAL_AGENT" \ --task "add-paypal" \ --summary "Add PayPal assistance to PaymentService" \ --scope symbol:PaymentService=extend ) PAYPAL_INTENT=$(printf '%s\n' "$PAYPAL_RESULT" | jq -er '.data.intent.id') printf '%s\n' "$PAYPAL_RESULT" | jq '.data.conflicts[] | {kind, severity, scope, explanation, suggestion}' printf '%s\n' "$PAYPAL_RESULT" | jq '.data.related_work[] | {agent, summary, asserted, overlap}'
The archetypal command prints the live finding from your local run. The second prints related_work: the another agent's intent and all overlapping scope with the two declared operations. Foremerge states what overlaps; you decide what it method and document that alongside foremerge measure record. No records need to change first. Inspect the captured, plainly tagged copy in examples/terminal-session.txt.
Claims add ownership environment without blocking either agent:
foremerge --json activity assertion \ --agent "$STRIPE_AGENT" \ --intent "$STRIPE_INTENT" \ --scope symbol:PaymentService \ --reason "Changing the provider boundary" >/dev/null foremerge --json activity assertion \ --agent "$PAYPAL_AGENT" \ --intent "$PAYPAL_INTENT" \ --scope symbol:PaymentService \ --reason "Adding another provider" | jq '.data | {advisory_only, warnings}' foremerge --json activity query --scope symbol:PaymentService | jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'
Both claims succeed. The second reply includes an overlap alert since a claim is a leased advisory, never exclusive ownership.
Recorded against the released 0.4.0 binary; all command and its output is real.
coding delegate A coding delegate B | | secluded worktree A secluded worktree B | | +--------- semantic events, not edits ----------+ | CLI / MCP / JSON API | Foremerge service / | \ SQLite coordination git CLI validation argv in <git-common-dir> | | \ Git repository / durable commits and refs Every frontend uses the identical assistance and store. The semantic chart is:
Agent → Task → Intent → Claim → Symbol → Dependency → ChangeSet → Test → Result → Decision → Provenance Mutations update typed SQLite projections, materialize chart edges, and append a hash-chained semantic event in one transaction. The log is helpful tamper evidence; it is not a distant character signature or distributed consensus.
Git worktrees: secluded files, shared awareness
Foremerge resolves the Git average directory and stores its default repository at:
<git-common-dir>/foremerge/state.sqlite3 Linked worktrees portion that average directory equal although their checked-out files are separate. Create a worktree alongside Foremerge's lean wrap around stock Git:
foremerge worktree create \ --branch agent/paypal \ --path ../payments-paypal \ --base HEAD foremerge --cwd ../payments-paypal --json delegate enroll \ --name paypal-agent \ --model "$ACTUAL_MODEL_ID"Another worktree in the identical repository sees the registered delegate and its intents immediately. You can override retention alongside --database PATH or FOREMERGE_DB, but all local delegate must item at the identical repository to share state. The MVP does not replicate SQLite throughout machines; do not infer distributed safety from a network-mounted database.
Foremerge snapshots Git province for ChangeSet fingerprints and accepted refs. It does not automatically merge, rebase, cherry-pick, push, or update a target branch.
INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL ─validate current fingerprint→ VALIDATED ─accept gates→ ACCEPTED ─record Git ref→ COMMITTED Supported range kinds are:
symbol api schema config infra test immigration env document component agreement domain Publish the narrowest helpful semantic scope. File paths solitary young female API, configuration, schema, infrastructure, and cross-language collisions.
Common commands:
| Boundary | Command |
|---|---|
| Register provenance | foremerge delegate enroll --name NAME --model MODEL |
| Publish intent | foremerge intent publish --agent ID --task TASK --summary TEXT --scope KIND:KEY=OPERATION |
| Claim scope | foremerge activity assertion --agent ID --intent ID --scope KIND:KEY |
| Start implementation | foremerge activity commencement INTENT_ID --agent AGENT_ID |
| Ask who is changing it | foremerge activity query --scope KIND:KEY |
| See what all delegate is doing | foremerge status |
| Preflight a plan | foremerge conflicts inspect --intent TEXT --scope KIND:KEY=OPERATION |
| Record what you concluded | foremerge measure document --agent ID --intent ID --related-intent-id ID --verdict V --rationale TEXT --action A |
| Send coordination | foremerge coordinate dispatch --from ID --to ID --message TEXT |
| Watch semantic events | foremerge activity observe --after-seq 0 |
Run foremerge <command> --help for the complete current flags. Global flags such as --json, --cwd, and --database may appear before or after subcommands.
A ChangeSet captures the agent/model, project and intent, affected files/symbols/contracts, dependencies, implementation summary, reported tests, decisions, provenance, worktree, fingerprint, status, and Git ref. The accepted applicant and its afterward landing commit are retained separately as accepted_commit and integration_commit.
The honest integration command is:
- Publish intent, assertion semantic scope, and grade implementation in progress.
- Work and commit on the secluded delegate branch.
- Publish a ChangeSet for that spotless candidate.
- Ask Foremerge to execute validation against its exact fingerprint.
- Resolve elevated conflicts, afterward obtain the still-clean, still-validated ref.
- Integrate alongside average Git or a drag request.
- Record the durable integration commit in Foremerge.
foremerge activity assertion \ --agent "$AGENT_ID" \ --intent "$INTENT_ID" \ --scope component:payments foremerge activity commencement "$INTENT_ID" --agent "$AGENT_ID" # Implement the alter and commit it on this secluded branch before publishing. CHANGESET_ID=$( foremerge --json changeset publish \ --agent "$AGENT_ID" \ --intent "$INTENT_ID" \ --summary "Introduce PaymentProvider and StripePaymentProvider" \ --file src/payments.rs \ --symbol PaymentProvider \ --symbol StripePaymentProvider \ --contract payment-provider \ --provenance-json '{"source":"coding-agent"}' \ --git-ref HEAD \ --worktree "$PWD" | jq -er '.data.id' ) foremerge changeset validate "$CHANGESET_ID" \ --worktree "$PWD" \ -- cargo test --all-targets foremerge changeset obtain "$CHANGESET_ID" --git-ref HEAD # Integrate alongside average Git, afterward document the commit that really landed. foremerge changeset commit "$CHANGESET_ID" --git-ref main
Agent-reported --reported-test COMMAND=STATUS values are provenance only. They do not fulfill acceptance. Foremerge-owned validation records the command argument vector, exit status, output, duration, and applicant fingerprint. Any detected alter following validation makes that attempt non-authoritative, but its output and changed-path diagnostic remain queryable alongside changeset attempts.
For trusted checks that create available untracked output, an controller may set exact or directory-prefix rules without changing tracked files:
foremerge validation-exclusions set \ --path coverage.log \ --path target/validation-reports/The normalized guideline digest is part of the applicant fingerprint, tracked changes are never excludable, MCP cannot alter the policy, and generated files must motionless be removed before acceptance. See ADR 0001.
Acceptance additionally requires a spotless worktree and no unresolved HIGH conflict, unless the visitant deliberately uses the apparent --allow-high-conflicts override together alongside --override-reason "...". Prefer resolving a conflict with an definitive rationale. Acceptance creates refs/foremerge/accepted/<changeset-id>; it does not merge code.
Validation commands run as trusted local code alongside your operating-system permissions. Foremerge does not sandbox them.
Run foremerge mcp complete stdio. MCP does not necessitate the HTTP daemon; the two are adapters complete the identical database.
| Tool | Purpose |
|---|---|
| register_agent | Record agent, model, capabilities, and worktree provenance |
| publish_intent | Announce planned work, province what it does to all scope, and obtain conflicts affirmative connected activity to assess |
| record_assessment | Record what you concluded concerning one connected intent and what you volition do |
| claim_work | Create leased advisory claims on semantic scopes |
| query_work | Find agents, intents, claims, ChangeSets, and conflicts |
| check_conflicts | Check a published or provisional intent before code changes |
| publish_changeset | Record implementation, tests, decisions, and Git provenance |
| coordinate_with_agent | Send a durable communication connected to a battle or ChangeSet |
| start_work | Advance claimed activity into implementation |
| resolve_conflict | Record an audited resolution for a durable conflict |
| run_verification | Run a trusted repository inspect by name, never raw MCP argv |
| accept_changeset | Apply final conflict, dependency, validation, and Git gates |
| record_commit | Record the genuine Git integration commit |
| discard_work | Preserve abandoned activity during releasing claims and blockers |
| list_agents | Read registered delegate provenance |
| get_intent | Read one intent and current battle snapshot |
| get_changeset | Read one ChangeSet and Git/provenance state |
| status | Read one accordant coordinator position snapshot |
Start from the valid minimal config in examples/mcp-config.json. It assumes the client launches foremerge alongside the repository as its operating directory. Clients without a repository working-directory environment should continue an absolute --database before mcp; get the Git average directory alternatively of assuming that a connected worktree's .git is a directory.
See agent client setup for the installer, native skill locations, client-specific MCP files, diagnostics, and harmless replacement rules. See MCP setup for transport behavior, schemas, named checks, example inputs, and multi-worktree configuration.
Source clones contain equal skills in .codex/skills, .claude/skills, .cursor/skills, the portable .agents/skills location, and the Claude Code plugin, affirmative portable Claude and Cursor MCP templates. A Cargo installation embeds the canonical accomplishment so foremerge setup can instal it into another repository without copying this origin tree.
The daemon defaults to authenticated loopback HTTP on http://127.0.0.1:47811. init creates a transporter token alongside personal file permissions anywhere the phase supports them.
In one terminal:
In another terminal, peruse the token way from Foremerge fairly than guessing it:
export FOREMERGE_URL=http://127.0.0.1:47811 TOKEN_FILE=$(foremerge --json init | jq -er '.data.token_file') FOREMERGE_TOKEN=$(tr -d '\r\n' < "$TOKEN_FILE") curl --fail --silent --show-error \ --header "Authorization: Bearer $FOREMERGE_TOKEN" \ --get "$FOREMERGE_URL/v1/work" \ --data-urlencode 'scope=symbol:PaymentService' | jq .
Do not print, commit, or portion the token. /healthz is database-free process liveness and /readyz is a bounded non-waiting shop probe; the two are public. Every /v1 route, including the paged event-chain audit, requires the token unless the daemon was deliberately started alongside --no-auth for a trusted local test. The MVP refuses non-loopback binds and is not a hardened multi-tenant service.
The CLI escape hatch foremerge petition says local auth automatically. A runnable curl walkthrough is in examples/api-requests.sh; the complete path and error reference is JSON API.
- Conflict finding is deterministic and explainable, but heuristic. It can miss synonymous concepts and notify on compatible work.
- Claims warn; they never fastener files, symbols, or agents.
- Passing validation proves lone that the recorded command passed for the recorded fingerprint, not that the test scheme was complete.
- Git refs and procedure results are stronger evidence than self-reported model, prompt, or test prose.
- The event sequence detects changes inner the retained chain; it is not a signature, distant attestation, or external checkpoint.
- Local SQLite is not shared-mode consensus, and the loopback transporter token is not a community deployment safety model.
- There are executable benchmark fixtures, a reproducible query harness, and a benchmark plan, but no published coordinated-vs-uncoordinated achievement results yet.
- Foremerge does not substitute code review, architecture ownership, CI, security scanning, Git hosting rules, or backups.
Read the complete limitations and rely model before using Foremerge as an integration gate.
| Document | What it answers |
|---|---|
| Architecture | Why one Rust binary, SQLite, Git CLI, and shared common-dir state? |
| Protocol | What do agents publish and when? |
| State model | Which transitions and invariants entrance work? |
| Conflict detection | Which deterministic rules create findings and suggestions? |
| Git integration | How do fingerprints, worktrees, and accepted refs behave? |
| Agent clients | How do Codex, Claude Code, and Cursor detect the accomplishment and MCP server? |
| MCP setup | How do clients configure and call the 18 lifecycle/read tools? |
| JSON API | Which routes, petition bodies, auth, and errors are shipped? |
| OpenAPI schema | What is the machine-readable HTTP contract? |
| Benchmark plan | How volition coordinated and uncoordinated runs be compared? |
| Validation elimination ADR | Which generated paths may validation ignore, and why? |
| Roadmap | What is current, next, later, or a non-goal? |
| Limitations | What does the MVP not guarantee? |
| Brand | Which mark, colors, type, icons, and CLI output rules use to any Foremerge surface? |
Also see the changelog, security policy, and code of conduct.
- Website: foremerge.com
- Crate: crates.io/crates/foremerge
- MCP Registry name: mcp-name: io.github.naw103/foremerge
Contributions are welcome, particularly protocol feedback on range vocabulary, conflict evidence, ChangeSet provenance, and verification policy. Read CONTRIBUTING.md, afterward run the complete local gate:
Foremerge is licensed under the Apache License 2.0.
