Foremerge 0.5.0 – Intent‑Based Conflict Detection for Parallel Coding Agents

Foremerge 0.5.0 enables agents to detect intent conflicts before any code is written

Foremerge 0.5.0 is a pre‑1.0, local‑first MVP that adds a coordination layer on top of Git. It lets multiple AI coding agents work in isolated Git worktrees, publish intent (semantic scopes and operations), and receive immediate, deterministic warnings when those intents collide. The protocol is advisory—agents are never locked out—but it prevents the silent “undo each other's work” problem that traditional line‑based merges miss.

---

How intent‑based conflict detection works

1. Agents announce what they will touch – instead of diffing text, an agent sends a JSON payload describing the target (e.g., symbol:PaymentService=replace).
2. All agents read a shared SQLite database stored in the repository’s Git common directory (<git‑common‑dir>/foremerge/state.sqlite3). The database is updated atomically, so every local agent sees the same view.
3. Foremerge compares intents deterministically and emits a HIGH advisory if two plans clash, along with an explanation and a suggested abstraction (e.g., PaymentProvider).
4. Agents decide how to proceed – they can adjust their plan, claim a scope, or continue with an advisory warning. No file locks are taken, avoiding deadlocks if an agent crashes.

"Foremerge never asks a model to judge conflicts, so the same inputs always produce the same answer." – Foremerge README

---

Example conflict that Git cannot see

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

Both agents modify different files, so Git merges without complaint. Foremerge detects that both declare the same symbol:PaymentService scope with opposing operations (replace vs extend) and raises a HIGH advisory, suggesting a shared abstraction such as PaymentProvider.

The terminal demo in the repository shows the conflict being reported before any worktree changes:

---

Quick‑start: see a conflict in under five minutes

1. Install – curl -fsSL https://foremerge.com/install.sh | sh (installs foremerge and the alias fmg).
2. Initialize – foremerge init creates the local SQLite state.
3. Wire agents – foremerge setup all registers the MCP skill for Claude, Codex, Cursor, etc.
4. Define a verification check – e.g., foremerge checks set test -- cargo test --all-targets.
5. Run the demo – register two agents, publish intents with scopes, and inspect the JSON conflict output using jq as shown in the README.

All commands are real; the demo output is captured in examples/terminal-session.txt.

---

Core data model and workflow

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

• Intent – semantic description of the planned change.
• Claim – advisory lease on a scope; multiple agents can claim the same scope, but a conflict warning is attached.
• ChangeSet – records the exact fingerprint of the code, the declared symbols, and the validation command.
• Verification gate – a user‑defined check (e.g., cargo test) that must pass on the exact fingerprint before a ChangeSet can be accepted.

The state transitions are deterministic and stored as hash‑chained events in SQLite, providing an auditable trail without requiring distributed consensus.

---

Integration with Git worktrees

Foremerge leverages Git’s common directory so that isolated worktrees share the same coordination database while keeping their file trees separate. Example to create a worktree and register an agent:

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"

Other worktrees immediately see the registered agent and its intents. The MVP does not replicate the SQLite store across machines; it is intended for local, single‑machine coordination.

---

Advisory claims vs. hard locks

Foremerge deliberately avoids file or symbol locks. A lock would stall the entire fleet if a single agent crashes, and it would create a queue that could deadlock. Instead, claims are advisory: they surface overlap warnings while allowing agents to continue working. The final acceptance gate (validation + conflict resolution) is the hard checkpoint before a commit is recorded in refs/foremerge/accepted/*.

---

Community feedback from Hacker News

• Version‑control for agents – A commenter noted that traditional VCS was designed for humans, not AI agents, and that Foremerge could be a step toward an “agent‑first” workflow.
• Custom solutions – Users reported ad‑hoc blackboard patterns and tools like weave but expressed a desire for a more systematic approach, which Foremerge aims to provide.
• Conflict relevance – Questions were raised about when a conflict should stop an agent. Foremerge’s current model flags any semantic overlap as HIGH advisory; the roadmap includes richer heuristics and user‑configurable severity.
• Future roadmap – The author mentioned plans for a treesitter‑based code graph to catch dependency‑level conflicts and push notifications for real‑time alerts.

---

Limitations and trust model (as documented)

• Conflict detection is deterministic but heuristic; false positives/negatives are possible.
• Claims are advisory only; they do not enforce exclusive ownership.
• Validation proves that a recorded command succeeded for a specific fingerprint, not that the test suite is exhaustive.
• The SQLite store is local‑only; there is no distributed consensus or multi‑tenant security model.
• No published benchmark results yet; performance comparisons are planned.
• Foremerge does not replace code review, CI, security scanning, or backup processes.

---

Extending and contributing

Foremerge is open source under Apache‑2.0. Contributions are encouraged, especially around scope vocabularies, conflict evidence, ChangeSet provenance, and verification policies. The repository includes:

• Full documentation (architecture, protocol, state model, conflict detection, Git integration, agent‑client setup, JSON API, OpenAPI schema, benchmark plan, limitations, roadmap).
• Example scripts (examples/terminal-session.txt, examples/api-requests.sh).
• Rust crate on crates.io (foremerge).
• MCP skill files for Claude, Codex, Cursor, and a portable .agents/skills directory.

To run the full test suite locally: make verify.

---

Bottom line

Foremerge 0.5.0 provides a practical, deterministic layer that lets AI coding agents publish and coordinate intent before touching code, catching semantic conflicts that Git’s line‑based merge cannot see. While still an MVP with local‑only storage and advisory warnings, it offers a concrete foundation for building agent‑first version‑control workflows.