Skip to content
Back to search

foremerge

Catch intent conflicts before code conflicts. The open-source coordination protocol for coding agents, built above Git.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/naw103/foremerge with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/naw103/foremerge'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/naw103--foremerge/badge.svg)](/listings/naw103--foremerge)

HTML

<a href="/listings/naw103--foremerge"><img src="/api/listings/naw103--foremerge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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.

Or do it yourself

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 install from npm on macOS or Linux with glibc. The package carries the same release binaries, so nothing is compiled or downloaded at install time:

npm install -g foremerge

The Windows npm package is not published yet; on Windows, use the releases page.

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](https://github.com/naw103/foremerge/releases). To update, upgrade the same way you installed, then re-run `foremerge setup` and restart your agent clients; [Upgrading Foremerge](docs/mcp-setup.md#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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "foremerge",
  3. "owner": {
  4. "name": "Nick Woodhead",
  5. "url": "https://github.com/naw103"
  6. },
  7. "metadata": {
  8. "description": "The Foremerge coordination plugin for Claude Code.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "foremerge",
  14. "source": "./plugins/foremerge",
  15. "description": "Agents publish intent and claim semantic scopes before writing code, so two plans that cannot both be true collide in a queryable store instead of in your merge. Local-first, deterministic, Apache-2.0. Requires the foremerge binary on PATH and a repository that has run foremerge init.",
  16. "category": "workflow",
  17. "keywords": [
  18. "git",
  19. "coordination",
  20. "parallel-agents",
  21. "worktrees",
  22. "merge-conflicts",
  23. "mcp"
  24. ]
  25. }
  26. ]
  27. }
README.md · README · 596 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1>Foremerge</h1>
  2. <p align="center">
  3. <img src="docs/assets/foremerge-readme-banner.png" alt="Foremerge: Catch intent conflicts before code conflicts" width="100%">
  4. </p>
  5. [![CI](https://github.com/naw103/foremerge/actions/workflows/ci.yml/badge.svg)](https://github.com/naw103/foremerge/actions/workflows/ci.yml)
  6. [![crates.io](https://img.shields.io/crates/v/foremerge.svg)](https://crates.io/crates/foremerge)
  7. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
  8. Foremerge is the open-source coordination protocol for coding agents, built
  9. above Git. Agents keep isolated worktrees while sharing intent, semantic
  10. claims, dependencies, provisional ChangeSets, decisions, validation, and
  11. provenance.
  12. | [**Tell your agent to install**](#quickstart-first-conflict-in-under-five-minutes) | → | **Done** | → | **See collisions before they land** |
  13. | :---: | :---: | :---: | :---: | :---: |
  14. | 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 |
  15. > **Status:** Foremerge `0.7.0` is a pre-1.0, local-first MVP. The CLI, JSON API,
  16. > MCP server, SQLite store, deterministic conflict detector, and
  17. > verification-gated lifecycle are implemented. Public schemas may still
  18. > change. Published benchmark results do not yet exist, and coordination
  19. > between machines is outside this project's scope.
  20. ## How it works
  21. Say you have two AI agents working on the same project at the same time. Each
  22. one gets its own copy of the code, so they never fight over files. Both finish.
  23. Both look correct. Then you find they undid each other's work.
  24. Git cannot warn you about that, because Git compares text and not intent. It
  25. will stop you when two agents edit the same part of the same file. What it
  26. cannot see is two edits that are each perfectly reasonable on their own and
  27. land in different files. If one agent moves every caller onto a new
  28. `StripePaymentService` while another adds PayPal support to the old
  29. `PaymentService`, nothing overlaps, so Git merges both without complaint and
  30. the PayPal work is left stranded on a class nothing calls any more.
  31. Foremerge fixes this by having agents announce what they are about to do,
  32. before they do it.
  33. 1. **Each agent says what it is about to touch.** Not the code, just the
  34. target, like "I am going to change the `sendEmail` function."
  35. 2. **Every agent reads from one shared list.** It is a small database inside
  36. your project's `.git` folder, so every agent on your machine sees the same
  37. picture, whether it is Claude, Codex, or Cursor.
  38. 3. **If two plans collide, you hear about it right away.** Foremerge names the
  39. two agents, explains why their plans clash, and suggests how to split the
  40. work. Both worktrees are still clean at that point, so no work has to be
  41. thrown away.
  42. Think of it as a shared whiteboard. Before an agent starts, it writes down what
  43. it is about to work on, and it reads what everyone else already wrote.
  44. Two things Foremerge deliberately does not do. It never locks a file or blocks
  45. an agent, because a single crashed agent would then stall the whole fleet, so
  46. the warnings are advisory and you stay in charge. And it never asks a model to
  47. judge conflicts, so the same inputs always produce the same answer.
  48. ## The conflict Git cannot see yet
  49. ```text
  50. Agent A: Replace PaymentService with StripePaymentService
  51. Agent B: Add PayPal support to PaymentService
  52. ```
  53. These agents can work in different trees without touching the same line. The
  54. plans still collide: one removes the extension point while the other depends on
  55. it.
  56. Both agents declare the same `symbol:PaymentService` scope, one saying it will
  57. `replace` it and the other that it will `extend` it. Foremerge compares those
  58. two declarations before either writes code, raises a `HIGH` advisory, and
  59. suggests coordinating on a stable abstraction such as `PaymentProvider`. That
  60. suggestion is explainable evidence, not an automatic architecture decision or a
  61. hard lock.
  62. Because the operation is declared rather than read out of the summary, it does
  63. not matter how either agent phrased its plan. "Consolidate payments onto
  64. Stripe" and "Replace PaymentService with Stripe" reach the same verdict.
  65. Git remains the durable repository. Foremerge supplies the missing shared
  66. awareness above it.
  67. ![Terminal rendering of an actual Foremerge release demo detecting the PaymentService conflict before either worktree changed](https://raw.githubusercontent.com/naw103/foremerge/main/docs/assets/foremerge-terminal-demo.png)
  68. _Rendered from the actual conflict fields captured by the `0.1.0`
  69. release-binary run in
  70. [`examples/terminal-session.txt`](examples/terminal-session.txt). The displayed
  71. command uses the shown `jq` filter; output is abridged for readability._
  72. ## Quickstart: first conflict in under five minutes
  73. ### Let your coding agent do it
  74. Paste this into Claude Code, Codex, or Cursor from inside the repository you
  75. want to coordinate:
  76. ```text
  77. Set up Foremerge in this repository so we can coordinate parallel agents.
  78. 1. Install it: curl -fsSL https://foremerge.com/install.sh | sh
  79. 2. Initialize: foremerge init
  80. 3. Wire this client and any others in use: foremerge setup all
  81. 4. Register the check I should be validated against, for example:
  82. foremerge checks set test -- cargo test --all-targets
  83. 5. Confirm: foremerge doctor --client all
  84. Then read the Foremerge skill that step 3 installed for this client and follow
  85. it from now on: publish your intent with semantic scopes before editing, claim
  86. the scope, and check for conflicts before you start.
  87. ```
  88. Adjust step 4 to whatever this repository's real test command is. Step 3 asks
  89. the client to enable an MCP server, so it will prompt you before doing so. The
  90. Codex registration is user level, but one registration serves every repository:
  91. start Codex inside the repository you want it to coordinate.
  92. ### Or do it yourself
  93. You need a recent Git and `jq`. Install a prebuilt, checksum-verified release
  94. binary (macOS and Linux; the script installs to `~/.local/bin`):
  95. ```sh
  96. curl -fsSL https://foremerge.com/install.sh | sh
  97. ```
  98. > [!TIP]
  99. > **Two commands, one program.** This installs `foremerge` and `fmg`, the same
  100. > binary under a shorter name, so `fmg status` and `foremerge status` do the
  101. > same thing. Examples below spell out `foremerge`; type whichever you prefer.
  102. Or install from npm (macOS, Linux with glibc, Windows x64). The package
  103. carries the same release binaries, so nothing is compiled or downloaded at
  104. install time:
  105. ```sh
  106. npm install -g foremerge
  107. ```
  108. Or build from source with Rust 1.85+: `cargo install --locked --git
  109. https://github.com/naw103/foremerge foremerge`, or `cargo install --locked
  110. --path .` from a checkout. Windows binaries are on the
  111. [releases page](https://github.com/naw103/foremerge/releases). To update,
  112. upgrade the same way you installed, then re-run `foremerge setup` and restart
  113. your agent clients; [Upgrading Foremerge](docs/mcp-setup.md#upgrading-foremerge)
  114. explains why each step matters. Then, inside the repository you want to
  115. coordinate:
  116. ```sh
  117. foremerge init
  118. foremerge doctor
  119. ```
  120. The installer, the release archives and `cargo install` all carry both names
  121. from 0.4.0 onward. If something else on your PATH already answers to `fmg`, the
  122. installer leaves it alone and says so rather than shadowing it.
  123. Install the native skill and MCP entry for any clients used in this repository,
  124. then define the trusted checks agents may request by name:
  125. ```sh
  126. foremerge setup all
  127. foremerge checks set test -- cargo test --all-targets
  128. foremerge doctor --client all
  129. ```
  130. Acceptance is verification-gated: Foremerge runs the check itself rather than
  131. taking an agent's word for it. Pick a check that is fast and that would actually
  132. catch a broken handoff, such as a build or a typecheck, rather than a full CI
  133. suite; this gate decides whether other agents may treat the work as done, and it
  134. does not replace CI. If this repository has nothing meaningful to verify, say so
  135. once rather than registering a check that always passes:
  136. ```sh
  137. foremerge checks policy advisory
  138. ```
  139. Work accepted that way is recorded as `UNVERIFIED` with the reason, so the audit
  140. trail never implies a check ran when none did. `foremerge doctor` reports
  141. whether the registered checks can actually run here, which matters in agent
  142. worktrees, because dependency directories are usually gitignored and
  143. `git worktree add` will not create them.
  144. Use `setup codex`, `setup claude`, or `setup cursor` for one client. Setup
  145. preserves unrelated configuration (including key order in project MCP JSON).
  146. Upgrading Foremerge refreshes its own unedited skill file in place, but a skill
  147. file you edited, or a differing Foremerge MCP entry, is never replaced unless
  148. you explicitly pass `--force`. `setup all` attempts every client and reports each
  149. result, exiting nonzero if any failed. The Codex MCP registration is user-level
  150. and serves every repository, resolved from the directory Codex is started in;
  151. see [agent client setup](docs/agent-clients.md).
  152. `init` creates local coordination state under the repository's Git common
  153. directory. It does not change tracked files. The following no-worktree sessions
  154. are enough to exercise pre-code detection; real coding agents should register
  155. their isolated worktrees and actual model identifiers.
  156. ```sh
  157. STRIPE_AGENT=$(
  158. foremerge --json agent register \
  159. --name stripe-agent \
  160. --no-worktree |
  161. jq -er '.data.id'
  162. )
  163. STRIPE_RESULT=$(
  164. foremerge --json intent publish \
  165. --agent "$STRIPE_AGENT" \
  166. --task "modernize-payments" \
  167. --summary "Replace PaymentService with StripePaymentService" \
  168. --scope symbol:PaymentService=replace
  169. )
  170. STRIPE_INTENT=$(printf '%s\n' "$STRIPE_RESULT" | jq -er '.data.intent.id')
  171. PAYPAL_AGENT=$(
  172. foremerge --json agent register \
  173. --name paypal-agent \
  174. --no-worktree |
  175. jq -er '.data.id'
  176. )
  177. PAYPAL_RESULT=$(
  178. foremerge --json intent publish \
  179. --agent "$PAYPAL_AGENT" \
  180. --task "add-paypal" \
  181. --summary "Add PayPal support to PaymentService" \
  182. --scope symbol:PaymentService=extend
  183. )
  184. PAYPAL_INTENT=$(printf '%s\n' "$PAYPAL_RESULT" | jq -er '.data.intent.id')
  185. printf '%s\n' "$PAYPAL_RESULT" |
  186. jq '.data.conflicts[] | {kind, severity, scope, explanation, suggestion}'
  187. printf '%s\n' "$PAYPAL_RESULT" |
  188. jq '.data.related_work[] | {agent, summary, asserted, overlap}'
  189. ```
  190. The first command prints the live finding from your local run. The second
  191. prints `related_work`: the other agent's intent and every overlapping scope
  192. with both declared operations. Foremerge states what overlaps; you decide what
  193. it means and record that with `foremerge assess record`. No files need to
  194. change first. Inspect the captured, clearly labeled transcript in
  195. [`examples/terminal-session.txt`](examples/terminal-session.txt).
  196. Claims add ownership context without blocking either agent:
  197. ```sh
  198. foremerge --json work claim \
  199. --agent "$STRIPE_AGENT" \
  200. --intent "$STRIPE_INTENT" \
  201. --scope symbol:PaymentService \
  202. --reason "Changing the provider boundary" >/dev/null
  203. foremerge --json work claim \
  204. --agent "$PAYPAL_AGENT" \
  205. --intent "$PAYPAL_INTENT" \
  206. --scope symbol:PaymentService \
  207. --reason "Adding another provider" |
  208. jq '.data | {advisory_only, warnings}'
  209. foremerge --json work query --scope symbol:PaymentService |
  210. jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'
  211. ```
  212. Both claims succeed. The second response includes an overlap warning because a
  213. claim is a leased advisory, never exclusive ownership.
  214. ![Real terminal recording: two agents declare intents on symbol:PaymentService and Foremerge raises the HIGH destructive_vs_additive finding before either writes code](docs/assets/foremerge-demo.gif)
  215. _Recorded against the released 0.4.0 binary; every command and its output is real._
  216. ## How it fits above Git
  217. ```text
  218. coding agent A coding agent B
  219. | |
  220. isolated worktree A isolated worktree B
  221. | |
  222. +--------- semantic events, not edits ----------+
  223. |
  224. CLI / MCP / JSON API
  225. |
  226. Foremerge service
  227. / | \
  228. SQLite coordination git CLI validation argv
  229. in <git-common-dir> | |
  230. \ Git repository /
  231. durable commits and refs
  232. ```
  233. Every frontend uses the same service and store. The semantic graph is:
  234. ```text
  235. Agent → Task → Intent → Claim → Symbol → Dependency
  236. → ChangeSet → Test → Result → Decision → Provenance
  237. ```
  238. Mutations update typed SQLite projections, materialize graph edges, and append a
  239. hash-chained semantic event in one transaction. The log is useful tamper
  240. evidence; it is not a remote identity signature or distributed consensus.
  241. ## Git worktrees: isolated files, shared awareness
  242. Foremerge resolves the Git common directory and stores its default database at:
  243. ```text
  244. <git-common-dir>/foremerge/state.sqlite3
  245. ```
  246. Linked worktrees share that common directory even though their checked-out
  247. files are separate. Create a worktree with Foremerge's thin wrapper around
  248. stock Git:
  249. ```sh
  250. foremerge worktree create \
  251. --branch agent/paypal \
  252. --path ../payments-paypal \
  253. --base HEAD
  254. foremerge --cwd ../payments-paypal --json agent register \
  255. --name paypal-agent \
  256. --model "$ACTUAL_MODEL_ID"
  257. ```
  258. Another worktree in the same repository sees the registered agent and its
  259. intents immediately. You can override storage with `--database PATH` or
  260. `FOREMERGE_DB`, but every local agent must point at the same database to share
  261. state. The MVP does not replicate SQLite across machines; do not infer
  262. distributed safety from a network-mounted database.
  263. Foremerge snapshots Git state for ChangeSet fingerprints and accepted refs. It
  264. does not automatically merge, rebase, cherry-pick, push, or update a target
  265. branch.
  266. ## Semantic workflow
  267. ```text
  268. INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL
  269. ─validate current fingerprint→ VALIDATED
  270. ─accept gates→ ACCEPTED ─record Git ref→ COMMITTED
  271. ```
  272. Supported scope kinds are:
  273. ```text
  274. symbol api schema config infra test migration env file component contract domain
  275. ```
  276. Publish the narrowest useful semantic scope. File paths alone miss API,
  277. configuration, schema, infrastructure, and cross-language collisions.
  278. Common commands:
  279. | Boundary | Command |
  280. | --- | --- |
  281. | Register provenance | `foremerge agent register --name NAME --model MODEL` |
  282. | Publish intent | `foremerge intent publish --agent ID --task TASK --summary TEXT --scope KIND:KEY=OPERATION` |
  283. | Claim scope | `foremerge work claim --agent ID --intent ID --scope KIND:KEY` |
  284. | Start implementation | `foremerge work start INTENT_ID --agent AGENT_ID` |
  285. | Ask who is changing it | `foremerge work query --scope KIND:KEY` |
  286. | See what every agent is doing | `foremerge status` |
  287. | Preflight a plan | `foremerge conflicts check --intent TEXT --scope KIND:KEY=OPERATION` |
  288. | Record what you concluded | `foremerge assess record --agent ID --intent ID --related-intent-id ID --verdict V --rationale TEXT --action A` |
  289. | Send coordination | `foremerge coordinate send --from ID --to ID --message TEXT` |
  290. | Watch semantic events | `foremerge work watch --after-seq 0` |
  291. Run `foremerge <command> --help` for the complete current flags. Global flags
  292. such as `--json`, `--cwd`, and `--database` may appear before or after
  293. subcommands.
  294. ## ChangeSets and the verification gate
  295. A ChangeSet captures the agent/model, task and intent, affected
  296. files/symbols/contracts, dependencies, implementation summary, reported tests,
  297. decisions, provenance, worktree, fingerprint, status, and Git ref.
  298. The accepted candidate and its later landing commit are retained separately as
  299. `accepted_commit` and `integration_commit`.
  300. The honest integration order is:
  301. 1. Publish intent, claim semantic scope, and mark implementation in progress.
  302. 2. Work and commit on the isolated agent branch.
  303. 3. Publish a ChangeSet for that clean candidate.
  304. 4. Ask Foremerge to execute validation against its exact fingerprint.
  305. 5. Resolve high conflicts, then accept the still-clean, still-validated ref.
  306. 6. Integrate with ordinary Git or a pull request.
  307. 7. Record the durable integration commit in Foremerge.
  308. ```sh
  309. foremerge work claim \
  310. --agent "$AGENT_ID" \
  311. --intent "$INTENT_ID" \
  312. --scope component:payments
  313. foremerge work start "$INTENT_ID" --agent "$AGENT_ID"
  314. # Implement the change and commit it on this isolated branch before publishing.
  315. CHANGESET_ID=$(
  316. foremerge --json changeset publish \
  317. --agent "$AGENT_ID" \
  318. --intent "$INTENT_ID" \
  319. --summary "Introduce PaymentProvider and StripePaymentProvider" \
  320. --file src/payments.rs \
  321. --symbol PaymentProvider \
  322. --symbol StripePaymentProvider \
  323. --contract payment-provider \
  324. --provenance-json '{"source":"coding-agent"}' \
  325. --git-ref HEAD \
  326. --worktree "$PWD" |
  327. jq -er '.data.id'
  328. )
  329. foremerge changeset validate "$CHANGESET_ID" \
  330. --worktree "$PWD" \
  331. -- cargo test --all-targets
  332. foremerge changeset accept "$CHANGESET_ID" --git-ref HEAD
  333. # Integrate with ordinary Git, then record the commit that actually landed.
  334. foremerge changeset commit "$CHANGESET_ID" --git-ref main
  335. ```
  336. Agent-reported `--reported-test COMMAND=STATUS` values are provenance only.
  337. They do not satisfy acceptance. Foremerge-owned validation records the command
  338. argument vector, exit status, output, duration, and candidate fingerprint. Any
  339. detected change after validation makes that attempt non-authoritative, but its
  340. output and changed-path diagnostic remain queryable with `changeset attempts`.
  341. For trusted checks that generate disposable untracked output, an operator may
  342. set exact or directory-prefix rules without changing tracked files:
  343. ```sh
  344. foremerge validation-exclusions set \
  345. --path coverage.log \
  346. --path target/validation-reports/
  347. ```
  348. The normalized policy digest is part of the candidate fingerprint, tracked
  349. changes are never excludable, MCP cannot change the policy, and generated files
  350. must still be removed before acceptance. See
  351. [ADR 0001](docs/adr/0001-validation-exclusion-rules.md).
  352. Acceptance also requires a clean worktree and no unresolved `HIGH` conflict,
  353. unless the caller deliberately uses the visible `--allow-high-conflicts`
  354. override together with `--override-reason "..."`. Prefer resolving a conflict
  355. with an explicit rationale. Acceptance creates
  356. `refs/foremerge/accepted/<changeset-id>`; it does not merge code.
  357. Validation commands run as trusted local code with your operating-system
  358. permissions. Foremerge does not sandbox them.
  359. ## Agent clients and MCP: complete lifecycle tools
  360. Run `foremerge mcp` over stdio. MCP does not require the HTTP daemon; both are
  361. adapters over the same database.
  362. | Tool | Purpose |
  363. | --- | --- |
  364. | `register_agent` | Record agent, model, capabilities, and worktree provenance |
  365. | `publish_intent` | Announce planned work, declare what it does to each scope, and receive conflicts plus related work to assess |
  366. | `record_assessment` | Record what you concluded about one related intent and what you will do |
  367. | `claim_work` | Create leased advisory claims on semantic scopes |
  368. | `query_work` | Find agents, intents, claims, ChangeSets, and conflicts |
  369. | `check_conflicts` | Check a published or provisional intent before code changes |
  370. | `publish_changeset` | Record implementation, tests, decisions, and Git provenance |
  371. | `coordinate_with_agent` | Send a durable message linked to a conflict or ChangeSet |
  372. | `start_work` | Advance claimed work into implementation |
  373. | `resolve_conflict` | Record an audited resolution for a durable conflict |
  374. | `run_verification` | Run a trusted repository check by name, never raw MCP argv |
  375. | `accept_changeset` | Apply final conflict, dependency, validation, and Git gates |
  376. | `record_commit` | Record the actual Git integration commit |
  377. | `discard_work` | Close abandoned work, or work that landed without acceptance, releasing claims and blockers |
  378. | `list_agents` | Read registered agent provenance |
  379. | `get_intent` | Read one intent and current conflict snapshot |
  380. | `get_changeset` | Read one ChangeSet and Git/provenance state |
  381. | `status` | Read one consistent coordinator status snapshot |
  382. Start from the valid minimal config in
  383. [`examples/mcp-config.json`](examples/mcp-config.json). It assumes the client
  384. launches `foremerge` with the repository as its working directory. Clients
  385. without a repository working-directory setting should pass an absolute
  386. `--database` before `mcp`; derive the Git common directory instead of assuming
  387. that a linked worktree's `.git` is a directory.
  388. See [agent client setup](docs/agent-clients.md) for the installer, native skill
  389. locations, client-specific MCP files, diagnostics, and safe replacement rules.
  390. See [MCP setup](docs/mcp-setup.md) for transport behavior, schemas, named checks,
  391. example inputs, and multi-worktree configuration.
  392. Source clones include equivalent skills in `.codex/skills`, `.claude/skills`,
  393. `.cursor/skills`, the portable `.agents/skills` location, and the Claude Code
  394. plugin, plus portable Claude and Cursor MCP templates. A Cargo installation
  395. embeds the canonical skill so `foremerge setup` can install it into another
  396. repository without copying this source tree.
  397. ## Local JSON API
  398. The daemon defaults to authenticated loopback HTTP on
  399. `http://127.0.0.1:47811`. `init` creates a bearer token with private file
  400. permissions where the platform supports them.
  401. In one terminal:
  402. ```sh
  403. foremerge daemon
  404. ```
  405. In another terminal, read the token path from Foremerge rather than guessing
  406. it:
  407. ```sh
  408. export FOREMERGE_URL=http://127.0.0.1:47811
  409. TOKEN_FILE=$(foremerge --json init | jq -er '.data.token_file')
  410. FOREMERGE_TOKEN=$(tr -d '\r\n' < "$TOKEN_FILE")
  411. curl --fail --silent --show-error \
  412. --header "Authorization: Bearer $FOREMERGE_TOKEN" \
  413. --get "$FOREMERGE_URL/v1/work" \
  414. --data-urlencode 'scope=symbol:PaymentService' |
  415. jq .
  416. ```
  417. Do not print, commit, or share the token. `/healthz` is database-free process
  418. liveness and `/readyz` is a bounded non-waiting store probe; both are public.
  419. Every `/v1` route, including the paged event-chain audit, requires the token unless
  420. the daemon was deliberately started with `--no-auth` for a trusted local test.
  421. The MVP refuses non-loopback binds and is not a hardened multi-tenant service.
  422. The CLI escape hatch `foremerge request` reads local auth automatically. A
  423. runnable curl walkthrough is in
  424. [`examples/api-requests.sh`](examples/api-requests.sh); the full route and error
  425. reference is [JSON API](docs/json-api.md).
  426. ## What the MVP deliberately does not claim
  427. - Conflict detection is deterministic and explainable, but heuristic. It can
  428. miss synonymous concepts and warn on compatible work.
  429. - Claims warn; they never lock files, symbols, or agents.
  430. - Passing validation proves only that the recorded command passed for the
  431. recorded fingerprint, not that the test plan was complete.
  432. - Git refs and process results are stronger evidence than self-reported model,
  433. prompt, or test prose.
  434. - The event chain detects changes inside the retained chain; it is not a
  435. signature, remote attestation, or external checkpoint.
  436. - Local SQLite is not shared-mode consensus, and the loopback bearer token is
  437. not a public deployment security model.
  438. - There are executable benchmark fixtures, a reproducible query harness, and a
  439. benchmark plan, but no published
  440. coordinated-vs-uncoordinated performance results yet.
  441. - Foremerge does not replace code review, architecture ownership, CI, security
  442. scanning, Git hosting rules, or backups.
  443. Read the complete [limitations and trust model](docs/limitations.md) before
  444. using Foremerge as an integration gate.
  445. ## Documentation
  446. | Document | What it answers |
  447. | --- | --- |
  448. | [Architecture](docs/architecture.md) | Why one Rust binary, SQLite, Git CLI, and shared common-dir state? |
  449. | [Protocol](docs/protocol.md) | What do agents publish and when? |
  450. | [State model](docs/state-model.md) | Which transitions and invariants gate work? |
  451. | [Conflict detection](docs/conflict-detection.md) | Which deterministic rules produce findings and suggestions? |
  452. | [Git integration](docs/git-integration.md) | How do fingerprints, worktrees, and accepted refs behave? |
  453. | [Agent clients](docs/agent-clients.md) | How do Codex, Claude Code, and Cursor discover the skill and MCP server? |
  454. | [MCP setup](docs/mcp-setup.md) | How do clients configure and call the 18 lifecycle/read tools? |
  455. | [JSON API](docs/json-api.md) | Which routes, request bodies, auth, and errors are shipped? |
  456. | [OpenAPI schema](docs/openapi.yaml) | What is the machine-readable HTTP contract? |
  457. | [Benchmark plan](docs/benchmark-plan.md) | How will coordinated and uncoordinated runs be compared? |
  458. | [Validation exclusion ADR](docs/adr/0001-validation-exclusion-rules.md) | Which generated paths may validation ignore, and why? |
  459. | [Roadmap](docs/roadmap.md) | What is current, next, later, or a non-goal? |
  460. | [Limitations](docs/limitations.md) | What does the MVP not guarantee? |
  461. | [Brand](docs/brand.md) | Which mark, colors, type, icons, and CLI output rules apply to any Foremerge surface? |
  462. Also see the [changelog](CHANGELOG.md), [security policy](SECURITY.md), and
  463. [code of conduct](CODE_OF_CONDUCT.md).
  464. ### Links
  465. - Website: [foremerge.com](https://foremerge.com)
  466. - Crate: [crates.io/crates/foremerge](https://crates.io/crates/foremerge)
  467. - MCP Registry name: mcp-name: io.github.naw103/foremerge
  468. ## Contributing and license
  469. Contributions are welcome, especially protocol feedback on scope vocabulary,
  470. conflict evidence, ChangeSet provenance, and verification policy. Read
  471. [CONTRIBUTING.md](CONTRIBUTING.md), then run the complete local gate:
  472. ```sh
  473. make verify
  474. ```
  475. Foremerge is licensed under the [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.