# AI use cases for Foremerge (naw103/foremerge)

Repo: [naw103/foremerge](https://github.com/naw103/foremerge) | Use cases: 4 | Page: https://dedupedai.com/use-cases/naw103-foremerge/

Foremerge is an open-source Rust coordination protocol that lets coding agents announce planned changes, see overlapping plans, and share claims and verification results above Git.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Catch conflicting agent plans before code is written: https://dedupedai.com/use-cases/naw103-foremerge/catch-conflicting-agent-plans-early/
- Set up Foremerge for a repo's coding agents: https://dedupedai.com/use-cases/naw103-foremerge/set-up-foremerge-for-a-coding-team/
- Claim a code area so other agents see ownership: https://dedupedai.com/use-cases/naw103-foremerge/claim-an-area-without-blocking-other-agents/
- Gate agent handoffs on a test command Foremerge runs: https://dedupedai.com/use-cases/naw103-foremerge/gate-agent-handoffs-on-a-real-check/

## How to catch conflicting agent plans before code is written with Foremerge

Repo: [naw103/foremerge](https://github.com/naw103/foremerge) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Publish each agent's planned symbol changes and get a conflict warning before either agent edits files.

**Who it is for:** A developer running two or more AI agents on one codebase, who worries that their separate changes will undo each other even though Git merges them cleanly.

**The problem:** Git only flags edits to the same lines, so two reasonable changes in different files can silently break each other.

**The outcome:** You see which agents' declared operations clash on the same symbol, with an explanation and a suggested split, while both worktrees are still clean.

### Steps

1. Register each agent with `foremerge --json agent register --name stripe-agent --no-worktree` and note the returned id. (inferred, check the README)
2. Publish the first plan with `foremerge --json intent publish --agent "$STRIPE_AGENT" --task "modernize-payments" --summary "Replace PaymentService with StripePaymentService" --scope symbol:PaymentService=replace`. (inferred, check the README)
3. Register a second agent and publish its plan with `--scope symbol:PaymentService=extend`.
4. Read the findings with `jq '.data.conflicts[] | {kind, severity, scope, explanation, suggestion}'` on the second publish result.
5. Record your decision with `foremerge assess record`.

### Prompt to paste into your agent

```text
In the <repo path> repository, register two agents with --no-worktree and publish intents that declare the same symbol:<target> scope with different operations. Expected output: a non-empty conflicts list in the second publish result with severity, explanation, and suggestion. Verify that the conflicts array is not empty before you report that the plans clash.
```

### Caveat

The README's example uses --no-worktree sessions to exercise detection, and real agents should register their isolated worktrees and model identifiers instead.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/naw103-foremerge/catch-conflicting-agent-plans-early/

## How to set up Foremerge for a repo's coding agents with Foremerge

Repo: [naw103/foremerge](https://github.com/naw103/foremerge) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Install Foremerge, initialize the repo, and wire up every agent client you use in one pass.

**Who it is for:** A team lead who wants Claude Code, Codex, or Cursor to coordinate on a repository and needs a one-time setup that works for each agent.

**The problem:** Each agent client needs its own skill and MCP entry, and setting them up by hand is easy to get wrong.

**The outcome:** The repository has local coordination state, every installed client has the Foremerge skill and MCP entry, and doctor reports the setup as working.

### Steps

1. Install with `curl -fsSL https://foremerge.com/install.sh | sh`.
2. Run `foremerge init` inside the repository.
3. Run `foremerge setup all` to wire every client you use.
4. Register the repository's real test command with `foremerge checks set test -- cargo test --all-targets`, replacing it with your own.
5. Run `foremerge doctor --client all` and confirm each client reports OK.

### Prompt to paste into your agent

```text
In the <repo path> repository, install Foremerge, run `foremerge init`, then run `foremerge setup all` and `foremerge doctor --client all`. Expected output: a per-client result from setup and a doctor report. Verify that setup exited with status zero, since the README says it exits nonzero if any client failed.
```

### Caveat

Setup asks the client to enable an MCP server and will prompt you before doing so, and the Codex registration is user level and serves every repository.

Risk, remote script: The install step pipes a script from Foremerge.com directly into sh, so review it first if your policy requires that.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/naw103-foremerge/set-up-foremerge-for-a-coding-team/

## How to claim a code area so other agents see ownership with Foremerge

Repo: [naw103/foremerge](https://github.com/naw103/foremerge) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Mark which agent is working on a symbol, with an advisory lease that never blocks anyone.

**Who it is for:** A developer whose agents may overlap on one area and who wants visible ownership without locking files.

**The problem:** Agents cannot see who is already working on a symbol, and file locks would stall the whole fleet if one agent crashed.

**The outcome:** Each agent's claim is visible to others in a query, and overlapping claims show as warnings rather than blocks.

### Steps

1. Claim the scope with `foremerge --json work claim --agent "$STRIPE_AGENT" --intent "$STRIPE_INTENT" --scope symbol:PaymentService --reason "Changing the provider boundary"`, using the agent and intent ids from your earlier publish. (inferred, check the README)
2. Claim the same scope for a second agent with its own intent id and a reason.
3. Read the second claim's `advisory_only` and `warnings` fields with `jq '.data | {advisory_only, warnings}'`.
4. List who holds the scope with `foremerge --json work query --scope symbol:PaymentService | jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'`. (inferred, check the README)

### Prompt to paste into your agent

```text
In the <repo path> repository, have two registered agents claim symbol:<target> with separate intents and reasons. Expected output: both claims succeed and the second response includes an overlap warning. Verify that advisory_only is true in the claim data before you tell anyone the scope is owned.
```

### Caveat

A claim is advisory and never exclusive ownership, so agents still have to read the warnings and decide for themselves.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/naw103-foremerge/claim-an-area-without-blocking-other-agents/

## How to gate agent handoffs on a test command Foremerge runs with Foremerge

Repo: [naw103/foremerge](https://github.com/naw103/foremerge) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Register a trusted check so work counts as done only after Foremerge runs it itself.

**Who it is for:** A developer who wants a finished agent's work verified by a command before other agents treat it as done.

**The problem:** An agent's own claim that its work passes is not enough for other agents to rely on.

**The outcome:** Accepted work is verified by a registered check that Foremerge runs, or is recorded as UNVERIFIED with the reason when no check was registered.

### Steps

1. Register a fast check that would catch a broken handoff, such as `foremerge checks set test -- cargo test --all-targets`, replacing it with your repository's command.
2. If the repository has nothing meaningful to verify, run `foremerge checks policy advisory` once instead of registering an always-passing check.
3. Run `foremerge doctor` to confirm the registered checks can run in agent worktrees.

### Prompt to paste into your agent

```text
In the <repo path> repository, register one check with `foremerge checks set` using the repository's real test command, then run `foremerge doctor`. Expected output: a doctor report stating whether the check can run in this worktree. Verify that the check does not always pass before you rely on it as a gate.
```

### Caveat

The gate decides whether other agents may treat work as done but does not replace CI, and the project is a pre-1.0 local-first MVP.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/naw103-foremerge/gate-agent-handoffs-on-a-real-check/