Foremerge

Foremerge 是一个构建于 Git 之上的开源协调协议，面向编码代理。代理在保持隔离工作树的同时，共享意图、语义声明、依赖、暂定 ChangeSets、决策、验证和来源信息。

状态： Foremerge 0.4.0 是一个 pre-1.0 的本地优先 MVP。CLI、JSON API、MCP 服务器、SQLite 存储、确定性冲突检测器和验证门控生命周期均已实现。公共 schema 仍可能变化。共享的多机模式和已发布的基准测试结果尚不存在。

工作原理

假设你有两个 AI 代理同时在同一个项目上工作。每个代理都有自己的代码副本，因此它们永远不会争抢文件。两者都完成了。两者看起来都正确。然后你发现它们相互撤销了对方的工作。

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

Foremerge 的解决方案是让代理在动手之前先宣布它们将要做什么。

1. 每个代理说明它将要接触什么。 不是代码，只是目标，例如“我将更改 sendEmail 函数。”

2. 每个代理都从一个共享列表中读取。 它是你项目 .git 文件夹内的一个小型数据库，因此你机器上的每个代理——无论是 Claude、Codex 还是 Cursor——看到的是同一幅图景。

3. 如果两个计划发生冲突，你会立刻知道。 Foremerge 会指名这两个代理，解释它们的计划为何冲突，并建议如何拆分工作。此时两个工作树仍然是干净的，因此不需要丢弃任何工作。

可以把它想象成一块共享白板。代理在开始之前，会写下它将要处理的内容，并读取其他所有人已经写下的内容。

有两件事是 Foremerge 刻意不做的。它从不锁定文件或阻塞代理，因为一个代理崩溃就会拖垮整个代理集群，所以警告只是建议，最终决定权在你。它也从不要求模型来评判冲突，因此相同的输入总是产生相同的答案。

Related MCP server: batuta-mcp

Git 尚无法看到的冲突

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

这些代理可以在不同的工作树中工作，不触碰同一行。但计划仍然冲突：一个移除了扩展点，而另一个依赖它。

两个代理都声明了相同的 symbol:PaymentService 作用域，一个说它将 replace 它，另一个说它将 extend 它。Foremerge 在任一代理写代码之前就比较这两个声明，提出 HIGH 级别的建议，并建议在 PaymentProvider 这样的稳定抽象上进行协调。这个建议是可解释的证据，而不是自动的架构决策或硬性锁定。

由于操作是显式声明的，而不是从摘要中读取出来的，因此任一代理如何表述其计划并不重要。“将支付整合到 Stripe”和“用 Stripe 替换 PaymentService”会得出相同的结论。

Git 仍然是持久化的仓库。Foremerge 在它之上补充了缺失的共享感知。

根据 0.1.0 发布二进制在 examples/terminal-session.txt 中运行时所捕获的实际冲突字段渲染。显示的命令使用了所展示的 jq 过滤器；输出为可读性而做了删节。

快速入门：五分钟内发现第一个冲突

让编码代理代劳

在你要协调的仓库中，将以下内容粘贴到 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 服务器，因此在启用之前它会向你确认。Codex 注册是用户级别的，但一次注册即可服务于所有仓库：在你要让 Codex 协调的仓库内启动 Codex。

或者自己动手

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

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

[!TIP] 两个命令，同一个程序。 这会安装 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 init
foremerge doctor

从 0.4.0 开始，安装程序、发布归档和 cargo install 都同时携带这两个名称。如果你的 PATH 上已经有某个程序响应 fmg，安装程序会放着它不管并明确说明，而不是将其遮蔽。

为这个仓库中使用的所有客户端安装原生技能和 MCP 条目，然后定义代理可以按名称请求的可信检查：

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

验收是验证门控的：Foremerge 会亲自运行检查，而不是听信代理的一面之词。选择一个快速且确实能捕获交接异常的检查，例如构建或类型检查，而不是完整的 CI 套件；这个门控决定其他代理是否可将工作视为已完成，并且它不替代 CI。如果这个仓库没有任何可验证的有意义内容，就一次性说明，而不是注册一个永远通过的检查：

foremerge checks policy advisory

以这种方式接受的工作会被记录为 UNVERIFIED 并附上原因，因此审计跟踪永远不会在检查未运行时暗示它已运行。foremerge doctor 会报告已注册的检查在这里是否真的可以运行，这在代理工作树中很重要，因为依赖目录通常会被 gitignore，而 git worktree add 不会创建它们。

对单个客户端使用 setup codex、setup claude 或 setup cursor。setup 会保留不相关的配置（包括项目 MCP JSON 中的键顺序）。升级 Foremerge 会在原位置刷新它自己未编辑过的技能文件，但你编辑过的技能文件，或不同的 Foremerge MCP 条目，绝不会被替换，除非你显式传入 --force。setup all 会尝试每个客户端并报告每个结果，如果有任何一个失败，则返回非零退出码。Codex MCP 注册是用户级别的，服务于所有仓库，根据启动 Codex 的目录进行解析；参见代理客户端设置。

init 会在仓库的 Git 公共目录下创建本地协调状态。它不会更改已跟踪的文件。下面的无工作树会话足以演练编码前检测；真正的编码代理应注册它们隔离的工作树和实际的模型标识符。

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：另一个代理的意图，以及与两个已声明操作重叠的每个作用域。Foremerge 指出哪些重叠；由你决定这意味着什么，并用 foremerge assess record 记录。无需先更改任何文件。在 examples/terminal-session.txt 中查看已捕获、带有清晰标签的会话记录。

声明在不阻塞任一代理的情况下添加上下文所有权：

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}'

两个声明都会成功。第二个响应包含一个重叠警告，因为声明是一种租借式的建议，绝不是排他性所有权。

它如何衔接在 Git 之上

  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 工作树：隔离的文件，共享的感知

Foremerge 解析 Git 公共目录，并将其默认数据库存储在：

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

关联的工作树共享该公共目录，即使它们检出的文件是相互独立的。使用 Foremerge 对原生 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"

同一个仓库中的另一个工作树会立即看到已注册的代理及其意图。你可以使用 --database PATH 或 FOREMERGE_DB 覆盖存储，但每个本地代理必须指向同一个数据库才能共享状态。MVP 不会跨机器复制 SQLite；不要从网络挂载的数据库推断分布式安全性。

Foremerge 会快照 Git 状态，用于 ChangeSet 指纹和已接受的 refs。它不会自动合并、变基、cherry-pick、推送或更新目标分支。

语义工作流

INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL
       ─validate current fingerprint→ VALIDATED
       ─accept gates→ ACCEPTED ─record Git ref→ COMMITTED

支持的作用域类型有：

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

发布最窄的有用语义作用域。仅靠文件路径会遗漏 API、配置、schema、基础设施和跨语言冲突。

常用命令：

运行 foremerge <command> --help 可查看当前完整的标志。全局标志（如 --json、--cwd 和 --database）可以出现在子命令之前或之后。

ChangeSets 与验证门禁

ChangeSet 记录智能体/模型、任务与意图、受影响的文件/符号/契约、依赖、实现摘要、报告的测试、决策、来源信息、工作树、指纹、状态以及 Git 引用。被接受的候选及其后续的落地提交分别保留为 accepted_commit 和 integration_commit。

真正的集成顺序如下：

1. 发布意图、认领语义作用域，并将实现标记为进行中。

2. 在隔离的智能体分支上工作并提交。

3. 为该干净的候选发布 ChangeSet。

4. 请求 Foremerge 根据其精确指纹执行验证。

5. 解决 HIGH 冲突，然后接受仍然干净且仍然通过验证的引用。

6. 使用普通 Git 或拉取请求进行集成。

7. 在 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

智能体报告的 --reported-test COMMAND=STATUS 值仅是来源信息，不满足验收要求。Foremerge 自身的验证会记录命令参数向量、退出状态、输出、耗时以及候选指纹。验证之后检测到的任何变更都会使该次尝试失去权威性，但其输出和变更路径诊断仍可通过 changeset attempts 查询。

对于会生成可丢弃的未跟踪输出的可信检查，操作员可以设置精确或目录前缀规则，而无需更改受跟踪的文件：

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

归一化后的策略摘要是候选指纹的一部分；受跟踪的变更永远不可被排除；MCP 无法更改该策略；生成的文件也必须在验收前移除。参见 ADR 0001。

验收还要求工作树干净且不存在未解决的 HIGH 冲突，除非调用者刻意使用可见的 --allow-high-conflicts 覆盖开关，并同时提供 --override-reason "..."。更推荐以明确的理由解决冲突。验收会创建 refs/foremerge/accepted/<changeset-id>；它不会合并代码。

验证命令以可信的本地代码形式、使用你的操作系统权限运行。Foremerge 不会对它们进行沙箱隔离。

智能体客户端与 MCP：完整的生命周期工具

通过 stdio 运行 foremerge mcp。MCP 不要求 HTTP 守护进程；两者都是同一数据库之上的适配器。

从 examples/mcp-config.json 中有效的最小配置开始。它假定客户端以仓库作为工作目录来启动 foremerge。未设置仓库工作目录的客户端应在 mcp 之前传入绝对的 --database；应推导出 Git 公共目录，而不是假定链接工作树的 .git 是一个目录。

安装程序、原生技能位置、客户端特定的 MCP 文件、诊断信息和安全替换规则，请参见 智能体客户端设置。传输行为、模式、命名检查、示例输入和多工作树配置，请参见 MCP 设置。

源码克隆包含 .codex/skills、.claude/skills 和 .cursor/skills 下的等价技能，以及可移植的 Claude 和 Cursor MCP 模板。Cargo 安装会嵌入规范技能，因此 foremerge setup 可以将其安装到另一个仓库，而无需复制此源码树。

本地 JSON API

守护进程默认在 http://127.0.0.1:47811 上提供需要认证的回环 HTTP。在平台支持的情况下，init 会以私有文件权限创建 bearer 令牌。

在一个终端中：

foremerge daemon

在另一个终端中，从 Foremerge 读取令牌路径，而不是猜测它：

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 .

不要打印、提交或分享令牌。/healthz 是不依赖数据库的进程存活检查，/readyz 是有界且非等待的存储探测；两者都是公开的。所有 /v1 路由（包括分页的事件链审计）都需要令牌，除非守护进程是为了可信的本地测试而刻意以 --no-auth 启动。MVP 拒绝非回环绑定，并且不是经过加固的多租户服务。

CLI 逃生舱口 foremerge request 会自动读取本地认证信息。可运行的 curl 演练位于 examples/api-requests.sh；完整的路由和错误参考见 JSON API。

MVP 刻意不声称的内容

• 冲突检测是确定性的、可解释的，但本质上是启发式的。它可能漏掉同义概念，也可能对兼容的工作发出警告。

• 认领只会发出警告；它们从不锁定文件、符号或智能体。

• 验证通过只证明所记录的命令针对所记录的指纹通过了，并不证明测试计划是完备的。

• Git 引用和进程结果是比自我报告的模型、提示词或测试描述更有力的证据。

• 事件链只能检测保留链内部的变更；它不是签名、远程证明或外部检查点。

• 本地 SQLite 不是共享模式下的共识机制，回环 bearer 令牌也不是面向公开部署的安全模型。

• 目前有可执行的基准测试夹具、可复现的查询框架和基准测试计划，但尚无已发布的协调与不协调的性能对比结果。

• Foremerge 不会取代代码审查、架构所有权、CI、安全扫描、Git 托管规则或备份。

在将 Foremerge 用作集成门禁之前，请阅读完整的 局限性与信任模型。

文档

另请参阅变更日志、安全政策和 行为准则。

贡献与许可

欢迎贡献，尤其是针对范围词汇、 冲突证据、ChangeSet 溯源和验证策略的协议反馈。请阅读 CONTRIBUTING.md，然后运行完整的本地门禁：

make verify

Foremerge 依据 Apache License 2.0 获得许可。