Show HN：Foremerge——在并行编码 Agent 产生代码冲突前发现意图冲突

Foremerge 是构建于 Git 之上的开源编码 Agent 协调协议。Agent 可保留隔离的 worktree，同时共享意图、语义声明、依赖关系、临时 ChangeSet、决策、验证信息和溯源信息。

让你的 Agent 安装	→	完成	→	在变更落地前发现冲突
将一行命令粘贴到 Claude Code、Codex 或 Cursor 中		它会安装并配置 Foremerge		即使位于不同 worktree，每个 Agent 也能看到其他 Agent 即将进行的修改

**状态：**Foremerge 0.5.0 是一个 pre-1.0、local-first 的 MVP。CLI、JSON API、MCP server、SQLite 存储、确定性冲突检测器以及验证门控的生命周期均已实现。公开 schema 仍可能变化。目前尚未发布基准测试结果，且机器之间的协调不在本项目范围内。

假设有两个 AI Agent 同时在同一个项目上工作。每个 Agent 都拥有自己的代码副本，因此它们从不会争抢文件。两者都完成了工作，看起来也都正确。随后你却发现，它们抵消了彼此的工作。

Git 无法对此发出警告，因为 Git 比较的是文本而不是意图。当两个 Agent 编辑同一文件的同一部分时，Git 会阻止你。但它无法看见两项各自都完全合理、且落在不同文件中的修改。如果一个 Agent 将所有调用方迁移到新的 StripePaymentService，而另一个 Agent 为旧的 PaymentService 添加 PayPal 支持，二者没有任何重叠，因此 Git 会毫无异议地合并二者；但 PayPal 的工作将被遗留在一个再也没有调用方的类上。

Foremerge 的解决方式是：让 Agent 在行动前先声明自己将要做什么。

1. **每个 Agent 说明自己将要触及什么。**不是代码本身，而是目标，例如“我要修改 sendEmail 函数”。
2. **每个 Agent 都从一份共享列表中读取信息。**它是项目 .git 文件夹中的一个小型数据库，因此机器上的每个 Agent——无论是 Claude、Codex 还是 Cursor——都能看到相同的全局视图。
3. **若两个计划发生碰撞，你会立即收到通知。**Foremerge 会指出两个 Agent 的名称，解释其计划为何冲突，并建议如何拆分工作。此时两个 worktree 仍然干净，因此无需丢弃任何工作。

把它想成一块共享白板。Agent 开始前，会写下自己准备处理的内容，并读取其他人已经写下的内容。

Foremerge 特意不做两件事。它绝不锁定文件或阻塞 Agent，因为单个崩溃的 Agent 否则会拖慢整个 Agent 集群；因此，这些警告仅为建议，控制权仍在你手中。它也绝不要求模型来判断冲突，因此相同输入始终产生相同答案。

Git 还无法看见的冲突

Agent A: Replace PaymentService with StripePaymentService
Agent B: Add PayPal support to PaymentService

这些 Agent 可以在不同的工作树中工作，且不会触及同一行代码。但计划仍然发生冲突：一个移除了扩展点，另一个则依赖该扩展点。

两个 Agent 都声明了相同的 symbol:PaymentService 范围：一个表示它将 replace 该范围，另一个表示将 extend 它。Foremerge 会在任一 Agent 写入代码之前比较这两项声明，发出 HIGH 级别建议，并建议围绕 PaymentProvider 等稳定抽象进行协调。该建议是可解释的证据，不是自动化的架构决策，也不是强制锁定。

由于声明的是操作而非从摘要中提取操作，因此 Agent 如何表述计划并不重要。“将支付功能整合到 Stripe”与“用 Stripe 替换 PaymentService”会得到相同结论。

Git 仍然是持久化代码仓库。Foremerge 则在其之上补足了缺失的共享感知能力。

根据 examples/terminal-session.txt 中 0.1.0 发布二进制运行捕获的实际冲突字段渲染。展示的命令使用所示的 jq 过滤器；为便于阅读，输出已作删节。

快速开始：五分钟内发现第一个冲突

让你的编码 Agent 来完成

在希望协调的代码仓库内，将以下内容粘贴到 Claude Code、Codex 或 Cursor：

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.

将第 4 步调整为该代码仓库实际使用的测试命令。第 3 步会要求客户端启用 MCP server，因此会在执行前提示你确认。Codex 的注册是用户级别的，但一次注册可服务所有代码仓库：请在希望让 Codex 协调的仓库内启动 Codex。

你需要较新的 Git 和 jq。可安装预构建且经过校验和验证的发布二进制文件（macOS 和 Linux；脚本会安装至 ~/.local/bin）：

curl -fsSL https://foremerge.com/install.sh | sh

提示

**两条命令，一个程序。**这会同时安装 foremerge 和 fmg，即同一个二进制文件的较短名称；因此 fmg status 与 foremerge status 的作用相同。下文示例均完整写作 foremerge；你可以输入自己偏好的任一名称。

或者，可使用 Rust 1.85+ 从源代码构建：cargo install --locked --git https://github.com/naw103/foremerge foremerge；也可在已检出的仓库中执行 cargo install --locked --path .。Windows 二进制文件位于发布页面。如需更新，请用与安装时相同的方式升级，然后重新运行 foremerge setup 并重启 Agent 客户端；升级 Foremerge解释了每一步的重要性。然后，在希望协调的仓库内执行：

foremerge init
foremerge doctor

从 0.4.0 起，安装脚本、发布归档和 cargo install 都会提供这两个名称。如果你的 PATH 中已有其他程序响应 fmg，安装程序会保留它，并说明这一情况，而不会将其覆盖。

为该仓库中使用的任意客户端安装原生 skill 和 MCP 条目，然后以名称定义 Agent 可以请求的可信检查项：

foremerge setup all
foremerge checks set test -- cargo test --all-targets
foremerge doctor --client all

验收受验证机制门控：Foremerge 会自行运行检查，而不是相信 Agent 的说法。应选择快速且能确实发现错误交接的检查项，例如构建或类型检查，而不是完整 CI 套件；该门控决定其他 Agent 能否将工作视为完成，但它不能替代 CI。若该仓库没有任何有意义的可验证内容，请明确说明一次，而不要注册一个始终通过的检查：

foremerge checks policy advisory

以此方式验收的工作会被标记为 UNVERIFIED，并记录原因，因此审计轨迹绝不会在没有运行检查时暗示检查已执行。foremerge doctor 会报告已注册检查项能否在当前环境中实际运行；这在 Agent worktree 中很重要，因为依赖目录通常会被 gitignore 忽略，而 git worktree add 不会创建它们。

如只配置一个客户端，请使用 setup codex、setup claude 或 setup cursor。设置操作会保留无关配置（包括项目 MCP JSON 中的键顺序）。升级 Foremerge 时，会原地刷新其自身未被编辑过的 skill 文件；但如果你编辑过 skill 文件，或存在不同的 Foremerge MCP 条目，除非你明确传入 --force，否则绝不会被替换。setup all 会尝试配置每一个客户端并报告各自结果；若有任一项失败，命令会以非零状态退出。Codex MCP 注册为用户级别，服务所有代码仓库，并从启动 Codex 的目录解析；详见Agent 客户端设置。

init 会在代码仓库的 Git common directory 下创建本地协调状态，不会改动受跟踪文件。以下无需 worktree 的会话已足以体验编码前检测；真实编码 Agent 应注册各自隔离的 worktree 和实际模型标识符。

STRIPE_AGENT=$( 
  foremerge --json agent register \
    --name stripe-agent \
    --no-worktree |
  jq -er '.data.id'
)

STRIPE_RESULT=$( 
  foremerge --json intent publish \
    --agent "$STRIPE_AGENT" \
    --task "modernize-payments" \
    --summary "Replace PaymentService with StripePaymentService" \
    --scope symbol:PaymentService=replace
)
STRIPE_INTENT=$(printf '%s\n' "$STRIPE_RESULT" | jq -er '.data.intent.id')

PAYPAL_AGENT=$( 
  foremerge --json agent register \
    --name paypal-agent \
    --no-worktree |
  jq -er '.data.id'
)

PAYPAL_RESULT=$( 
  foremerge --json intent publish \
    --agent "$PAYPAL_AGENT" \
    --task "add-paypal" \
    --summary "Add PayPal support 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}'

第一条命令会输出本地运行时发现的实时问题。第二条命令会输出 related_work：即另一个 Agent 的意图，以及每个重叠范围和双方声明的操作。Foremerge 说明重叠之处；你决定这意味着什么，并通过 foremerge assess record 记录这一判断。无需先修改任何文件。请查看 examples/terminal-session.txt 中已捕获、并有明确标注的完整记录。

声明（Claim）会增加所有权上下文，但不会阻止任何 Agent：

foremerge --json work claim \
  --agent "$STRIPE_AGENT" \
  --intent "$STRIPE_INTENT" \
  --scope symbol:PaymentService \
  --reason "Changing the provider boundary" >/dev/null

foremerge --json work claim \
  --agent "$PAYPAL_AGENT" \
  --intent "$PAYPAL_INTENT" \
  --scope symbol:PaymentService \
  --reason "Adding another provider" |
  jq '.data | {advisory_only, warnings}'

foremerge --json work query --scope symbol:PaymentService |
  jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'

两项声明都会成功。第二个响应会包含重叠警告，因为声明是租期制的建议，而非排他性所有权。

使用已发布的 0.4.0 二进制版本录制；每条命令及其输出均为真实结果。

coding agent A                                  coding agent B
      |                                               |
isolated worktree A                            isolated 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

每个前端都使用相同的服务和存储。语义图如下：

Agent → Task → Intent → Claim → Symbol → Dependency
      → ChangeSet → Test → Result → Decision → Provenance

变更操作会在一个事务中更新带类型的 SQLite 投影、实体化图边，并追加一条哈希链式语义事件。该日志可作为有用的防篡改证据；它不是远程身份签名，也不是分布式共识。

Git worktree：隔离文件，共享感知

Foremerge 会解析 Git common directory，并将默认数据库存储在：

<git-common-dir>/foremerge/state.sqlite3

链接的 worktree 共享该 common directory，即使它们检出的

Foremerge is the open-source coordination protocol for coding agents, built above Git. Agents keep isolated worktrees while sharing intent, semantic claims, dependencies, provisional ChangeSets, decisions, validation, and provenance.

Tell your agent to install	→	Done	→	See collisions before they land
Paste one line into Claude Code, Codex, or Cursor		It installs Foremerge and wires itself up		Every agent sees what the others are about to change, even in separate worktrees

Status: Foremerge 0.5.0 is a pre-1.0, local-first MVP. The CLI, JSON API, MCP server, SQLite store, deterministic conflict detector, and verification-gated lifecycle are implemented. Public schemas may still change. Published benchmark results do not yet exist, and coordination between machines is outside this project's scope.

Say you have two AI agents working on the same project at the same time. Each one gets its own copy of the code, so they never fight over files. Both finish. Both look correct. Then you find they undid each other's work.

Git cannot warn you about that, because Git compares text and not intent. It will stop you when two agents edit the same part of the same file. What it cannot see is two edits that are each perfectly reasonable on their own and land in different files. If one agent moves every caller onto a new StripePaymentService while another adds PayPal support to the old PaymentService, nothing overlaps, so Git merges both without complaint and the PayPal work is left stranded on a class nothing calls any more.

Foremerge fixes this by having agents announce what they are about to do, before they do it.

1. Each agent says what it is about to touch. Not the code, just the target, like "I am going to change the sendEmail function."
2. Every agent reads from one shared list. It is a small database inside your project's .git folder, so every agent on your machine sees the same picture, whether it is Claude, Codex, or Cursor.
3. If two plans collide, you hear about it right away. Foremerge names the two agents, explains why their plans clash, and suggests how to split the work. Both worktrees are still clean at that point, so no work has to be thrown away.

Think of it as a shared whiteboard. Before an agent starts, it writes down what it is about to work on, and it reads what everyone else already wrote.

Two things Foremerge deliberately does not do. It never locks a file or blocks an agent, because a single crashed agent would then stall the whole fleet, so the warnings are advisory and you stay in charge. And it never asks a model to judge conflicts, so the same inputs always produce the same answer.

The conflict Git cannot see yet

Agent A: Replace PaymentService with StripePaymentService
Agent B: Add PayPal support to PaymentService

These agents can work in different trees without touching the same line. The plans still collide: one removes the extension point while the other depends on it.

Both agents declare the same symbol:PaymentService scope, one saying it will replace it and the other that it will extend it. Foremerge compares those two declarations before either writes code, raises a HIGH advisory, and suggests coordinating on a stable abstraction such as PaymentProvider. That suggestion is explainable evidence, not an automatic architecture decision or a hard lock.

Because the operation is declared rather than read out of the summary, it does not matter how either agent phrased its plan. "Consolidate payments onto Stripe" and "Replace PaymentService with Stripe" reach the same verdict.

Git remains the durable repository. Foremerge supplies the missing shared awareness above it.

Rendered from the actual conflict fields captured by the0.1.0 release-binary run in examples/terminal-session.txt. The displayed command uses the shown jq filter; output is abridged for readability.

Quickstart: first conflict in under five minutes

Let your coding agent do it

Paste this into Claude Code, Codex, or Cursor from inside 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 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.

Adjust step 4 to whatever this repository's real test command is. Step 3 asks the client to enable an MCP server, so it will prompt you before doing so. The Codex registration is user level, but one registration serves every repository: start Codex inside the repository you want it to coordinate.

You need a recent Git and jq. Install a prebuilt, checksum-verified release binary (macOS and Linux; the script installs to ~/.local/bin):

curl -fsSL https://foremerge.com/install.sh | sh

Tip

Two commands, one program. This installs foremerge and fmg, the same binary under a shorter name, so fmg status and foremerge status do the same thing. Examples below spell out foremerge; type whichever you prefer.

Or build from source with Rust 1.85+: cargo install --locked --git https://github.com/naw103/foremerge foremerge, or cargo install --locked --path . from a checkout. Windows binaries are on the releases page. To update, upgrade the same way you installed, then re-run foremerge setup and restart your agent clients; Upgrading Foremerge explains why each step matters. Then, inside the repository you want to coordinate:

foremerge init
foremerge doctor

The installer, the release archives and cargo install all carry both names from 0.4.0 onward. If something else on your PATH already answers to fmg, the installer leaves it alone and says so rather than shadowing it.

Install the native skill and MCP entry for any clients used in this repository, then define the trusted checks agents may request by name:

foremerge setup all
foremerge checks set test -- cargo test --all-targets
foremerge doctor --client all

Acceptance is verification-gated: Foremerge runs the check itself rather than taking an agent's word for it. Pick a check that is fast and that would actually catch a broken handoff, such as a build or a typecheck, rather than a full CI suite; this gate decides whether other agents may treat the work as done, and it does not replace CI. If this repository has nothing meaningful to verify, say so once rather than registering a check that always passes:

foremerge checks policy advisory

Work accepted that way is recorded as UNVERIFIED with the reason, so the audit trail never implies a check ran when none did. foremerge doctor reports whether the registered checks can actually run here, which matters in agent worktrees, because dependency directories are usually gitignored and git worktree add will not create them.

Use setup codex, setup claude, or setup cursor for one client. Setup preserves unrelated configuration (including key order in project MCP JSON). Upgrading Foremerge refreshes its own unedited skill file in place, but a skill file you edited, or a differing Foremerge MCP entry, is never replaced unless you explicitly pass --force. setup all attempts every client and reports each result, exiting nonzero if any failed. The Codex MCP registration is user-level and serves every repository, resolved from the directory Codex is started in; see agent client setup.

init creates local coordination state under the repository's Git common directory. It does not change tracked files. The following no-worktree sessions are enough to exercise pre-code detection; real coding agents should register their isolated worktrees and actual model identifiers.

STRIPE_AGENT=$(
  foremerge --json agent register \
    --name stripe-agent \
    --no-worktree |
  jq -er '.data.id'
)

STRIPE_RESULT=$(
  foremerge --json intent publish \
    --agent "$STRIPE_AGENT" \
    --task "modernize-payments" \
    --summary "Replace PaymentService with StripePaymentService" \
    --scope symbol:PaymentService=replace
)
STRIPE_INTENT=$(printf '%s\n' "$STRIPE_RESULT" | jq -er '.data.intent.id')

PAYPAL_AGENT=$(
  foremerge --json agent register \
    --name paypal-agent \
    --no-worktree |
  jq -er '.data.id'
)

PAYPAL_RESULT=$(
  foremerge --json intent publish \
    --agent "$PAYPAL_AGENT" \
    --task "add-paypal" \
    --summary "Add PayPal support 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 first command prints the live finding from your local run. The second prints related_work: the other agent's intent and every overlapping scope with both declared operations. Foremerge states what overlaps; you decide what it means and record that with foremerge assess record. No files need to change first. Inspect the captured, clearly labeled transcript in examples/terminal-session.txt.

Claims add ownership context without blocking either agent:

foremerge --json work claim \
  --agent "$STRIPE_AGENT" \
  --intent "$STRIPE_INTENT" \
  --scope symbol:PaymentService \
  --reason "Changing the provider boundary" >/dev/null

foremerge --json work claim \
  --agent "$PAYPAL_AGENT" \
  --intent "$PAYPAL_INTENT" \
  --scope symbol:PaymentService \
  --reason "Adding another provider" |
  jq '.data | {advisory_only, warnings}'

foremerge --json work query --scope symbol:PaymentService |
  jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'

Both claims succeed. The second response includes an overlap warning because a claim is a leased advisory, never exclusive ownership.

Recorded against the released 0.4.0 binary; every command and its output is real.

  coding agent A                                  coding agent B
        |                                               |
  isolated worktree A                            isolated 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 same service and store. The semantic graph is:

Agent → Task → Intent → Claim → Symbol → Dependency
      → ChangeSet → Test → Result → Decision → Provenance

Mutations update typed SQLite projections, materialize graph edges, and append a hash-chained semantic event in one transaction. The log is useful tamper evidence; it is not a remote identity signature or distributed consensus.

Git worktrees: isolated files, shared awareness

Foremerge resolves the Git common directory and stores its default database at:

<git-common-dir>/foremerge/state.sqlite3

Linked worktrees share that common directory even though their checked-out files are separate. Create a worktree with Foremerge's thin wrapper around stock Git:

foremerge worktree create \
  --branch agent/paypal \
  --path ../payments-paypal \
  --base HEAD

foremerge --cwd ../payments-paypal --json agent register \
  --name paypal-agent \
  --model "$ACTUAL_MODEL_ID"

Another worktree in the same repository sees the registered agent and its intents immediately. You can override storage with --database PATH or FOREMERGE_DB, but every local agent must point at the same database to share state. The MVP does not replicate SQLite across machines; do not infer distributed safety from a network-mounted database.

Foremerge snapshots Git state 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 scope kinds are:

symbol api schema config infra test migration env file component contract domain

Publish the narrowest useful semantic scope. File paths alone miss API, configuration, schema, infrastructure, and cross-language collisions.

Common commands:

Boundary	Command
Register provenance	foremerge agent register --name NAME --model MODEL
Publish intent	foremerge intent publish --agent ID --task TASK --summary TEXT --scope KIND:KEY=OPERATION
Claim scope	foremerge work claim --agent ID --intent ID --scope KIND:KEY
Start implementation	foremerge work start INTENT_ID --agent AGENT_ID
Ask who is changing it	foremerge work query --scope KIND:KEY
See what every agent is doing	foremerge status
Preflight a plan	foremerge conflicts check --intent TEXT --scope KIND:KEY=OPERATION
Record what you concluded	foremerge assess record --agent ID --intent ID --related-intent-id ID --verdict V --rationale TEXT --action A
Send coordination	foremerge coordinate send --from ID --to ID --message TEXT
Watch semantic events	foremerge work watch --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.

ChangeSets and the verification gate

A ChangeSet captures the agent/model, task and intent, affected files/symbols/contracts, dependencies, implementation summary, reported tests, decisions, provenance, worktree, fingerprint, status, and Git ref. The accepted candidate and its later landing commit are retained separately as accepted_commit and integration_commit.

The honest integration order is:

1. Publish intent, claim semantic scope, and mark implementation in progress.
2. Work and commit on the isolated agent branch.
3. Publish a ChangeSet for that clean candidate.
4. Ask Foremerge to execute validation against its exact fingerprint.
5. Resolve high conflicts, then accept the still-clean, still-validated ref.
6. Integrate with ordinary Git or a pull request.
7. Record the durable integration commit in Foremerge.

foremerge work claim \
  --agent "$AGENT_ID" \
  --intent "$INTENT_ID" \
  --scope component:payments
foremerge work start "$INTENT_ID" --agent "$AGENT_ID"

# Implement the change and commit it on this isolated 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 accept "$CHANGESET_ID" --git-ref HEAD

# Integrate with ordinary Git, then record the commit that actually landed.
foremerge changeset commit "$CHANGESET_ID" --git-ref main

Agent-reported --reported-test COMMAND=STATUS values are provenance only. They do not satisfy acceptance. Foremerge-owned validation records the command argument vector, exit status, output, duration, and candidate fingerprint. Any detected change after validation makes that attempt non-authoritative, but its output and changed-path diagnostic remain queryable with changeset attempts.

For trusted checks that generate disposable untracked output, an operator may set exact or directory-prefix rules without changing tracked files:

foremerge validation-exclusions set \
  --path coverage.log \
  --path target/validation-reports/

The normalized policy digest is part of the candidate fingerprint, tracked changes are never excludable, MCP cannot change the policy, and generated files must still be removed before acceptance. See ADR 0001.

Acceptance also requires a clean worktree and no unresolved HIGH conflict, unless the caller deliberately uses the visible --allow-high-conflicts override together with --override-reason "...". Prefer resolving a conflict with an explicit rationale. Acceptance creates refs/foremerge/accepted/<changeset-id>; it does not merge code.

Validation commands run as trusted local code with your operating-system permissions. Foremerge does not sandbox them.

Agent clients and MCP: complete lifecycle tools

Run foremerge mcp over stdio. MCP does not require the HTTP daemon; both are adapters over the same database.

Tool	Purpose
register_agent	Record agent, model, capabilities, and worktree provenance
publish_intent	Announce planned work, declare what it does to each scope, and receive conflicts plus related work to assess
record_assessment	Record what you concluded about one related intent and what you will 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 message linked to a conflict or ChangeSet
start_work	Advance claimed work into implementation
resolve_conflict	Record an audited resolution for a durable conflict
run_verification	Run a trusted repository check by name, never raw MCP argv
accept_changeset	Apply final conflict, dependency, validation, and Git gates
record_commit	Record the actual Git integration commit
discard_work	Preserve abandoned work while releasing claims and blockers
list_agents	Read registered agent provenance
get_intent	Read one intent and current conflict snapshot
get_changeset	Read one ChangeSet and Git/provenance state
status	Read one consistent coordinator status snapshot

Start from the valid minimal config in examples/mcp-config.json. It assumes the client launches foremerge with the repository as its working directory. Clients without a repository working-directory setting should pass an absolute --database before mcp; derive the Git common directory instead of assuming that a linked worktree's .git is a directory.

See agent client setup for the installer, native skill locations, client-specific MCP files, diagnostics, and safe replacement rules. See MCP setup for transport behavior, schemas, named checks, example inputs, and multi-worktree configuration.

Source clones include equivalent skills in .codex/skills, .claude/skills, .cursor/skills, the portable .agents/skills location, and the Claude Code plugin, plus portable Claude and Cursor MCP templates. A Cargo installation embeds the canonical skill so foremerge setup can install it into another repository without copying this source tree.

The daemon defaults to authenticated loopback HTTP on http://127.0.0.1:47811. init creates a bearer token with private file permissions where the platform supports them.

In one terminal:

In another terminal, read the token path from Foremerge rather 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 share the token. /healthz is database-free process liveness and /readyz is a bounded non-waiting store probe; both are public. Every /v1 route, including the paged event-chain audit, requires the token unless the daemon was deliberately started with --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 request reads local auth automatically. A runnable curl walkthrough is in examples/api-requests.sh; the full route and error reference is JSON API.

What the MVP deliberately does not claim

• Conflict detection is deterministic and explainable, but heuristic. It can miss synonymous concepts and warn on compatible work.
• Claims warn; they never lock files, symbols, or agents.
• Passing validation proves only that the recorded command passed for the recorded fingerprint, not that the test plan was complete.
• Git refs and process results are stronger evidence than self-reported model, prompt, or test prose.
• The event chain detects changes inside the retained chain; it is not a signature, remote attestation, or external checkpoint.
• Local SQLite is not shared-mode consensus, and the loopback bearer token is not a public deployment security model.
• There are executable benchmark fixtures, a reproducible query harness, and a benchmark plan, but no published coordinated-vs-uncoordinated performance results yet.
• Foremerge does not replace code review, architecture ownership, CI, security scanning, Git hosting rules, or backups.

Read the complete limitations and trust 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 gate work?
Conflict detection	Which deterministic rules produce findings and suggestions?
Git integration	How do fingerprints, worktrees, and accepted refs behave?
Agent clients	How do Codex, Claude Code, and Cursor discover the skill and MCP server?
MCP setup	How do clients configure and call the 18 lifecycle/read tools?
JSON API	Which routes, request bodies, auth, and errors are shipped?
OpenAPI schema	What is the machine-readable HTTP contract?
Benchmark plan	How will coordinated and uncoordinated runs be compared?
Validation exclusion 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 apply to any Foremerge surface?

Also see the changelog, security policy, and code of conduct.

Contributions are welcome, especially protocol feedback on scope vocabulary, conflict evidence, ChangeSet provenance, and verification policy. Read CONTRIBUTING.md, then run the complete local gate:

Foremerge is licensed under the Apache License 2.0.