This is the Foremerge newsletter. We build GPTree with several coding agents working one repository at once, and Foremerge is the coordination layer built originally as an internal tool. The issues here are about what breaks when agents work in parallel and what we changed because of it. Here’s the article that started it.
Originally published on foremerge.com on August 27, 2026.
We have several coding agents working the same repository at once: Claude Code, Codex, and Cursor, each in its own git worktree. The failure that finally made us build tooling for it was small and completely silent.
One session was told to replace PaymentService with a Stripe-specific implementation. Another was told to add PayPal support to PaymentService. Different worktrees. Different files. No textual conflict. Git merged both branches cleanly, and the second change now depended on an extension point the first had deleted. Nothing in the toolchain highlighted it at any moment.
Git compares diffs but cannot compare plans, at least not semantically when they collide with what someone else is working on.
Worktrees isolate files, not plans #
Worktrees became the standard answer to parallel agents for a good reason: two sessions editing one checkout will overwrite each other’s files and poison each other’s context and isolated checkouts fix that completely.
But three failure modes survive file isolation, because they were never about files:
- Destructive versus additive. One agent removes or replaces a thing another agent is building on. The example above. Merges clean, breaks the design.
- Duplicate work. Two agents solve the same problem from different angles because nothing assigned ownership. You pay twice and then pay again to reconcile.
- Contract drift. One agent changes an API, a schema, or a config contract while another codes against the old shape. Compiles, runs, disagrees at runtime.
A shared task list helps with the second one, if every agent reads it, every time. Nothing in that setup catches the first or third, because the collision is between intentions, and intentions live in prompts, not in any file a tool can watch.
Declare the work before doing it #
Foremerge is the internal tool we built for this, open-sourced this week. It is a coordination protocol that sits above Git. Agents declare what they are about to do, before they do it, in a form precise enough to check.
A declaration is an intent with one or more semantic scopes, each carrying an operation:
foremerge intent publish \
--agent "$AGENT" \
--task "modernize-payments" \
--summary "Replace PaymentService with StripePaymentService" \
--scope symbol:PaymentService=replace
Scopes are not file paths. The vocabulary covers symbol, api, schema, config, migration, contract, and more, because file paths miss API, schema, configuration, and cross-language collisions entirely. The operation (replace, extend, and so on) is declared rather than parsed out of the summary so it does not matter how the agent phrased its plan.
When a second agent declares work on the same scope, deterministic rules compare the declarations and raise a finding while both pieces of work are still plans. This is real output from 0.4.0, captured while writing this post:
{
"kind": "destructive_vs_additive",
"severity": "HIGH",
"scope": { "kind": "symbol", "key": "PaymentService" },
"explanation": "One intent will replace `PaymentService` while the other will extend it; both declare the same semantic scope.",
"suggestion": "Coordinate on a stable `PaymentProvider` contract first, then implement StripePaymentProvider and PayPalPaymentProvider behind it and migrate callers deliberately. This is a heuristic suggestion, not an automatic design decision."
}
The finding names the rule that fired, explains itself, and suggests a resolution. It does not block anyone. Claims in Foremerge are leased and advisory: overlap produces a warning and shared context, never a lock, because two agents can often work the same region compatibly and a lock would serialize work that did not need serializing.
The other half of the protocol is evidence. When an agent finishes, it publishes a ChangeSet, and acceptance is gated on verification that Foremerge runs itself. It runs your named check (a build, a typecheck, a test target you registered) executed against the exact candidate fingerprint. An agent saying “tests pass” is recorded as provenance so it does not satisfy the gate. If the tree changed after validation, the attempt is non-authoritative and the gate flags it.
Mechanically it is one Rust binary. The CLI, a local JSON API, and an MCP server are adapters over the same SQLite store, which lives inside your repository’s git common directory, which is exactly why worktrees work well with it. Linked worktrees share that directory, so every agent in the repo sees the same declarations while keeping isolated files. Local-first, no cloud, Apache-2.0.
The five-minute version #
The fastest way to get set up is to let your 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.
The MCP server gives the agent the full lifecycle as tools: publish intent, claim scope, check conflicts, publish ChangeSets, run verification, record the commit that landed. Set it up once per repository and every agent connected to that repository shares the same awareness.
Doing it by hand instead is just a single install line, foremerge init, and then the commands in the README, which walks two throwaway agents into the exact conflict above in under five minutes.
What it deliberately does not claim #
This is a pre-1.0, local-first MVP, and the parts it does not do are documented as carefully as the parts it does:
- Detection is deterministic and explainable, but heuristic. It can miss synonymous concepts and warn on work that was always compatible.
- Claims warn. They never lock files, symbols, or agents.
- Passing validation proves that the recorded command passed for the recorded fingerprint. Nothing more.
- The store is per-machine SQLite. Shared multi-machine mode does not exist yet.
- There is a reproducible benchmark harness in the repo, but no published coordinated-versus-uncoordinated results yet. Performance claims wait for numbers.
The full list is in docs/limitations.md. We think a coordination tool that overclaims is worse than no coordination tool because severity is the signal an agent uses to decide what to stop for, and a false HIGH is worse than silence.
Where this goes #
The protocol is the part we most want feedback on: Is the scope vocabulary the right shape? Where would the conflict rules warn on compatible work in your codebase, and which collisions would they miss? Issues and Discussions are open.
- Repo: github.com/naw103/foremerge
- Site and install: foremerge.com
- Crate:
cargo install foremerge
If you run parallel agents and have hit collisions in worktrees, we would genuinely like to hear what they looked like.