DEV Community: Nick Woodhead

Coding agents stop mid-task. Our coordination store had 3,896 stale conflicts

Nick Woodhead — Mon, 02 Nov 2026 16:15:51 +0000

Foremerge records what each coding agent plans to change before it edits anything, and raises a finding when two plans cannot both be true. That only works if the record is current. Version 0.6.0 fixes the way it was not.

Agents stop without saying goodbye

An agent session ends without closing its intent far more often than you would guess. A context window fills up. A laptop lid closes. A scheduled run reaches the end of its slot. The intent the agent published stays open, its claims expire, and nobody closes it.

Foremerge treated that abandoned work as live. Every later intent on the same files was compared against it, and each comparison that found something was recorded. One of our own repositories, where scheduled agents and interactive sessions share a single coordination store, reached 3,896 open conflicts, 98% of them with no live agent on either side. A new intent on a busy file opened with about 40 recorded against it, and the ones worth reading were buried in the ones that were not.

This is a problem you only get from running several agents at once over a long period. One agent, one session, and the record stays tidy by accident.

What 0.6.0 changes

A finding below HIGH against work whose agent has stopped is no longer recorded. An intent counts as stopped under the same test work adopt already applied: it sits in INTENT, CLAIMED, IN_PROGRESS or PROVISIONAL, it holds no live claim, and its agent has made no call that writes to the record for two hours (reads and validation runs do not count).
Stopped work is still listed in related_work, last, marked with owner_stopped_since, and needs no assessment. Another agent can see it there and adopt it. A what-if check_conflicts applies the same rule and names what it left out under stopped_work.
If the agent was only quiet, its next call, an adoption of its work, or a check that validates it records the findings that were skipped in the meantime, unless the other agent has gone quiet too. Pairs already on record are left alone, settled or not. If the agent never returns, those findings are never recorded. The stopped work stays listed in related_work, but nothing requires anyone to act on it. This leans on severity: everything below HIGH counts as safe to skip, so a finding rated too low goes with the rest.
The agent skill and the discard_work description now tell an agent to close its intent before it stops. Work that reached Git without going through acceptance, because no named check is registered or a maintainer committed a batch by hand, can be closed with foremerge work discard --landed REF.

Why HIGH findings are still recorded

HIGH findings gate acceptance, and an agent that was only quiet must not lose that protection. So the gate is unchanged. A stopped intent whose declared plan genuinely contradicts yours still asserts, and you still have to deal with it before your ChangeSet is accepted. The rule only removes the advisory noise underneath that line.

What you see now

Before, a new intent on a crowded file came back with a long list of recorded conflicts, most of them against intents whose agents had been gone for days, and nothing in the list told you which was which. Now the same intent comes back with the live findings only. The stopped work is still there at the end of related_work, each entry carrying owner_stopped_since with the time its agent went quiet, so you can see what was set aside and pick it up if it is worth finishing.

Conflicts already on record are not touched by the upgrade. To clear a backlog like ours, close the stopped intents.

The migration change

Foremerge used to migrate a ledger's schema as a side effect of opening it, and every command opens the ledger, including the ones that only read. A status run by a newer binary from the wrong directory migrated a real repository's shared coordination store and locked every older client out of it.

Foremerge no longer migrates on open. A command that meets an older ledger refuses it with MIGRATION_REQUIRED and leaves the file exactly as it was. foremerge ledger migrate does the migration and nothing else does: it refuses to run while another process has the ledger open, copies the ledger with its WAL contents into a timestamped backup directory, checks the copy's integrity, migrates, and prints how to roll back. Without --yes it only reports what it would do.

The schema itself has not changed since 0.4.0, so upgrading from any 0.4.x or 0.5.x build needs no migration and both versions read the same store. Only a ledger last opened by 0.3.x needs the step. This is why 0.6.0 is a minor version rather than a patch.

Installing it

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

That installs a checksum-verified release binary on macOS and Linux. On npm, which also covers Windows x64:

npm install -g foremerge

The full list of changes is in the 0.6.0 release notes.

The general lesson

If you are building coordination for agents, the failure mode to design for is not the agent that disagrees with another agent. It is the agent that never comes back. Human collaborators close their tickets, eventually, because somebody asks them to. An agent whose process exited has no such pressure, and a store that assumes otherwise will slowly fill with work that nobody is doing and nobody will ever withdraw.

What is an intent conflict?

Nick Woodhead — Sun, 01 Nov 2026 19:58:42 +0000

An intent conflict is a contradiction between two declared plans that cannot both be carried out as written. Two coding agents each say what they are about to change and what they will do to it, and the plans disagree: one will replace a thing, the other will build on it. It is called an intent conflict because it exists at the moment the plans are made, before any line of code does.

What does an intent conflict look like?

Take a payments class that two agents have been given work on.

Agent A is told to modernize payments. It plans to replace PaymentService, moving every caller onto a new PaymentProvider interface.
Agent B is told to add PayPal. It plans to extend PaymentService with a PayPal method.

Each plan is sensible alone. Together they are not possible: B is adding to a class A is retiring. If each agent works in its own worktree, the files never touch. When the branches merge, Git may find nothing to complain about, and the new PayPal code ends up attached to a class that no longer has callers. Worktrees do not remove this collision, they move it to merge time.

An intent conflict is what you want surfaced here, while both agents are still at the planning stage. With Foremerge, each agent publishes an intent and the scopes it will change, with the operation on each. When the second agent declares symbol:PaymentService=extend against the first agent's replace, the comparison raises a destructive_vs_additive finding at HIGH severity, with both worktrees still clean.

How is it different from a merge conflict?

A merge conflict is a statement about text: two branches changed the same lines, and Git cannot choose between them. It appears when the work is finished and the branches are combined.

An intent conflict is a statement about plans. It does not need overlapping lines, overlapping files or even overlapping time. And it can be present when the merge is perfectly clean, which is the case that costs the most, because nothing reports it.

	Merge conflict	Intent conflict
Compares	changed lines	declared plans
Appears	when branches are combined	when the second plan is declared
Needs overlapping text	yes	no
Can exist with a clean merge	no	yes

What is it not?

Not a prediction that the code will break. It says two plans contradict each other. Whether the damage is a failing test or a quiet dead end depends on the code.
Not a replacement for Git. Git is still the right tool for text. The intent record sits above it.
Not the same as orchestration. An orchestrator decides who does what. An intent conflict is what is left when two agents each did what they were told and the instructions disagreed. See orchestrators and coordinators.

Where does the term sit?

Git made disagreement between people a named object: a conflict, appearing at a known moment, resolved before anything lands. Agent coordination applies the same idea one layer up. Git can only see a collision when two agents touch the same lines, and the expensive collisions are decided earlier, in the plans. See the coordination layer.

If you only ever run one coding agent at a time, you will not meet an intent conflict. If you run several, the cheapest check is to write down what each will change and what it will do to it, and read two entries side by side before anyone starts. Foremerge is open source (Apache-2.0), pre-1.0 and local-first, so it works on one machine and has no shared mode yet.

Git worktrees stop your coding agents overwriting each other’s files. They do not stop their plans contradicting each other. Sometimes Git flags it at merge. Sometimes it merges clean and nothing reports it.

Nick Woodhead — Thu, 29 Oct 2026 18:29:12 +0000

Nick Woodhead

Oct 29

Worktrees do not remove the collision. They move it to merge time.

#ai #git #devtools #productivity

8 min read

Worktrees do not remove the collision. They move it to merge time.

Nick Woodhead — Thu, 29 Oct 2026 18:27:30 +0000

Git worktrees give each coding agent its own checkout, so the agents stop overwriting each other's files. They do not remove the collision between what the agents are trying to do. That collision is still there, and with worktrees you find it later, when you merge the branches.

Sometimes Git stops you at that point. Sometimes it merges cleanly and the damage is only visible if you go looking. Below is a small repository you can build in two minutes that shows both outcomes, then what you can check with Git alone and what you need to move earlier.

A merge-time collision is a conflict between two agents' plans that nothing detects until their branches are combined. The plans were incompatible from the moment both were made. Worktrees keep the files apart while the work happens, so the incompatibility sits unseen until integration.

What do worktrees isolate, and what do they leave alone?

A worktree is a second checkout of the same repository, on its own branch, in its own directory. Two agents in two worktrees cannot overwrite each other's half-written files, break each other's builds with a stray install, or read stale code because the other agent changed it underneath.

That is the whole of it, and it is worth having. But look at what is not on the list:

What each agent has decided to build. That lives in a prompt, not in a file.
What each agent assumes will still exist. Agent B adds a method to a class because the class is there. It has no way to know Agent A is retiring it.
The order in which the work should land. Worktrees do not know that one task has to be merged before the other is started.

Isolation helps while the agents work. It decides nothing about whether their work belongs in the same codebase.

What does Git report when you merge?

Git merges by comparing changed lines against a common ancestor. I ran the same two-agent task through a throwaway repository three different ways, with Git 2.51.0, and Git gave three different answers.

What Agent A did	What Agent B did	What Git said at merge
Deleted `payments.py` after moving callers off it	Added a method to `payments.py`	`CONFLICT (modify/delete)`. Stopped.
Rewrote the call in `checkout.py`	Added a new function next to that call in `checkout.py`	`CONFLICT (content)`. Stopped.
Moved callers to a new class and left `payments.py` in place	Added a method to `payments.py` and a new file that uses it	Clean merge. No output.

The first two are the cases people mean when they say worktrees "work": the plans touch the same file, Git notices, and a person decides. The third is the one that matters here.

So Git's answer depends on how the agents happened to arrange their edits, not on whether the plans were compatible. The same disagreement is loud in one run and silent in the next.

What does the clean merge look like?

Here is the third case from the table, end to end. The task: Agent A is asked to replace PaymentService with StripePaymentService. Agent B is asked to add PayPal support to PaymentService. Each gets its own worktree and branch.

git worktree add ../agent-a -b agent/stripe
git worktree add ../agent-b -b agent/paypal

Agent A creates shop/stripe_payments.py, moves every caller in shop/checkout.py to the new class, and leaves a note at the top of shop/payments.py: # Deprecated: callers moved to StripePaymentService. Delete next release. It commits.

Agent B adds a charge_paypal method to the end of shop/payments.py and a new file, shop/paypal_checkout.py, that calls it. It commits.

Then the integration, in the main checkout:

$ git merge agent/stripe
 shop/checkout.py        | 4 ++--
 shop/stripe_payments.py | 3 +++
 2 files changed, 5 insertions(+), 2 deletions(-)
 create mode 100644 shop/stripe_payments.py

$ git merge agent/paypal
 shop/payments.py        | 3 +++
 shop/paypal_checkout.py | 4 ++++
 2 files changed, 7 insertions(+)
 create mode 100644 shop/paypal_checkout.py

$ git status --short
(clean)

Now look at what the merged repository says:

$ head -2 shop/payments.py
# Deprecated: callers moved to StripePaymentService. Delete next release.
class PaymentService:

$ grep -rn "PaymentService" shop/ | grep -v Stripe
shop/payments.py:2:class PaymentService:
shop/paypal_checkout.py:1:from shop.payments import PaymentService
shop/paypal_checkout.py:4:    return PaymentService().charge_paypal(cents)

$ python3 -c "from shop.checkout import checkout; from shop.paypal_checkout import checkout_paypal; print(checkout(500)); print(checkout_paypal(500))"
charged 500 via stripe
charged 500 via paypal

Both paths run. Nothing fails. And the codebase now has one class marked for deletion, with PayPal, a new feature, built on top of it. The next person to follow the deprecation note deletes the class and takes PayPal with it. Or they leave it, and the repository permanently has two payment classes, one per gateway.

No test fails, because each branch's tests passed on its own and the merged tests exercise two working paths. Each agent also reported success, and it was right. The only thing wrong is a contradiction between two plans, and no tool in the standard pipeline reads plans.

Why is merge time the expensive moment?

The incompatibility existed the second the second agent started. What changes with time is the cost of resolving it. This is reasoning, not a measurement: I have no timing data to give you.

At planning time, you change a sentence in a prompt. Nothing has been written.
While the agents work, you stop one and redirect it. You lose part of a session.
At merge time, both agents have finished and both branches are green. Now you are choosing between two completed pieces of work, or rewriting one to sit on the other. If the conflict is the loud kind, you also have to understand both diffs to resolve it.
After merge, the conflict is in the codebase, and the only evidence of it is a deprecation note and a class that should not have grown.

Worktrees move the discovery from the first row of that list to the third or fourth. They make the work itself smoother and the surprise later. That trade is usually fine with two agents and a small task. It stops being fine as the number of agents grows, because the number of pairs of plans grows faster than the number of agents.

What can you do with Git alone?

Quite a lot, and you should do all of it before you add a tool.

Decide the order of destructive work. If a task replaces, removes, renames or migrates something, nobody else should be editing that thing. Run the destructive task first, merge it, then start the others from the merged commit.
Define the boundary before you split. If two tasks meet at an interface, make one small change that defines it, merge it, and start both agents from that commit. In the example, that is a PaymentProvider interface first, then Stripe and PayPal behind it.
Assign by what a task changes, not by its name. "Modernize payments" and "add PayPal" sound like two features. They change one class.
Test the merged result, not each branch. Merge into a throwaway integration branch and run your real checks there. In the example this would have passed, so it catches the loud failures and not the quiet one, but it catches a lot.
Ask Git whether a merge is clean before you do it. git merge-tree --write-tree agent/stripe agent/paypal performs the merge in memory and reports conflicts without touching your working tree. It is quick, and it gives you the same answer the merge would, which in the third case is "clean". Treat that answer as a statement about text only.
Write the plans down where every agent reads them. A shared file that lists each task, what it changes and what operation it performs catches duplicate work. It catches replace-versus-extend only if someone reads two entries side by side and notices.

All of these are the same move: get the plans into a form you can compare before the code exists. Past two or three agents, the weak point is that a person has to do the comparing.

What changes if the plans are compared before the code?

That is the step we built Foremerge for. It is an open-source coordination protocol that sits above Git. Each agent declares what it is about to change, and what it will do to it, before it edits anything.

foremerge intent publish \
  --agent "$AGENT" \
  --task "modernize-payments" \
  --summary "Replace PaymentService with StripePaymentService" \
  --scope symbol:PaymentService=replace

When another agent declares symbol:PaymentService=extend, the comparison raises a destructive_vs_additive finding at HIGH severity, while both worktrees are still clean:

{
  "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 does not block anyone. Claims are advisory, so two agents can still work the same area when that is fine. It is information for the agent or the person, delivered at the cheapest point on the list above. The store is a SQLite file in the repository's Git directory, which every linked worktree shares, so the agents keep isolated files and see the same declarations.

The limits are real. It trusts the declaration: an agent that says extend and then rewrites the class is not caught, though the declaration and the diff are both on record. A scope on a whole class does not match a scope on one of its methods in this release. Two names for the same concept can slip past it. It does not replace review, CI or someone owning the architecture, and a missing finding never shows that two changes are compatible. There are no published results on time saved.

Do you need any of this?

If you run one agent at a time, no. If your agents work on clearly separate parts of the code and you merge in sequence, worktrees and the list above are enough. The collision gets expensive when several agents run at once on one codebase, when they come from different tools, or when you cannot read all their plans before they finish.

Frequently asked questions

Do git worktrees prevent merge conflicts between AI agents?

No. Worktrees stop agents from overwriting each other's files while they work. Conflicts still appear when the branches are merged, and plans that contradict each other without touching the same lines merge cleanly and are not reported at all.

Why did Git merge two agents' branches with no conflict and the code still not make sense?

Git compares changed lines against a common ancestor, not intentions. If one agent retires a class and another builds on it in a different file, no lines overlap. The merge is clean and the codebase now contradicts itself.

Does git merge-tree tell me whether two agent branches are compatible?

It tells you whether Git can combine them without a textual conflict, without changing your working tree. That is useful and fast. A clean answer says nothing about whether the two plans are compatible, and in the example above it is clean.

Should one agent finish before the next starts?

When a task replaces, removes or renames something other work depends on, yes: run it first, merge it, and start the others from the result. Tasks that only add or extend different things can run in parallel.

Should I merge each agent's branch separately or together?

Merge into a throwaway integration branch and run your real checks on the combined result before anything reaches your main branch. Each branch passing its own tests tells you about that branch only.

Does Foremerge replace worktrees?

No. Worktrees isolate files and Foremerge shares plans, so you use both. Foremerge reads the same store from every worktree and from Claude Code, Codex and Cursor, and its claims never lock anything.

If you only ever run one agent, skip this

If you run two or more agents on one repository, worktrees handle the files and a comparison of declared plans handles the part Git cannot see. Foremerge is one Rust binary, local-first and Apache-2.0. Install it with curl -fsSL https://foremerge.com/install.sh | sh, then run foremerge init. One limit to start with: it can only compare what agents declare.

[Boost]

Nick Woodhead — Mon, 19 Oct 2026 18:40:10 +0000

Nick Woodhead

Oct 17

Translating Technical Debt

#technicaldebt #leadership #programming #career

5 min read

[Boost]

Nick Woodhead — Mon, 19 Oct 2026 00:05:49 +0000

Nick Woodhead

Oct 18

Running multiple Claude Code agents in parallel: what worktrees cannot see

#ai #git #devtools #productivity

11 min read

Running multiple Claude Code agents in parallel: what worktrees cannot see

Nick Woodhead — Sun, 18 Oct 2026 23:54:25 +0000

If you only ever run one coding agent, you do not need most of this. You're also probably working more inefficiently than you could be.

If you run two or more: give each Claude Code session its own Git worktree, give each one a task that changes different things, and run your real checks on the merged result rather than on each branch. Worktrees stop agents from overwriting each other's files. They do not stop two agents from making plans that cannot both be true, and Git will merge those plans cleanly, because Git compares text, not intent.

That second problem has a name. A semantic conflict is when two changes merge without a textual conflict but contradict each other in meaning: one agent removes something another agent is building on, two agents build the same thing twice, or one changes a contract that the other is still coding against. Git cannot report it, because no two edits touched the same lines.

This post covers the setup that works, what Git can and cannot see, how to split work so semantic conflicts are rarer, and the part no amount of task splitting fixes.

The setup: one agent, one worktree, one branch

Running two agents in one checkout fails fast. They overwrite each other's half-written files, one session's install step breaks the other's build, and each agent's picture of the code goes stale under it. The standard fix is a Git worktree per agent: a separate checkout of the same repository on its own branch, sharing one history.

Claude Code has this built in. Run it once per session, with a different name each time:

claude --worktree feature-auth
claude --worktree add-paypal

Or use stock Git, which works the same way for any agent:

git worktree add ../myapp-paypal -b agent/paypal
cd ../myapp-paypal

A few things worktrees do not isolate, and that will bite you the first week:

Gitignored dependencies. git worktree add checks out tracked files only. node_modules, virtualenvs and build directories do not come with it, so each worktree needs its own install before its tests mean anything.
Ports, databases and other shared services. Two dev servers on one port, or two agents migrating one local database, collide no matter how the files are laid out.
Branches. Git lets a branch be checked out in only one worktree at a time, so each agent needs its own branch.
Integration. Someone still merges the branches. Pick one integrator, a person or one designated session, and do not let several agents each resolve the same conflict their own way.

With that in place, file collisions are solved. What is left is everything that was never about files.

What Git can see, and what it cannot

Git merges by comparing changed lines against a common ancestor. That makes it very good at one kind of collision and blind to the rest.

What the two agents did	What Git reports	What actually happened
Edited the same lines of the same file	Conflict	Git stops you. This is the case it handles.
Edited different parts of the same file	Usually a clean merge	Often fine. Sometimes not.
One renamed a function, the other added a call to the old name	Clean merge	The build fails afterwards. Your CI catches it, if it runs on the merged result.
One replaced a class, the other extended it	Clean merge	It may compile. The design is broken.
Both built the same feature from different angles	Clean merge, or an add/add conflict	You paid twice and now reconcile two versions.
One changed a schema or config contract, the other coded against the old shape	Clean merge	It builds, runs, and disagrees at runtime.

Only the first row is visible to Git. The rename row is visible to a compiler. The last three are visible to nothing in a standard toolchain, because the collision is between two plans, and plans live in prompts.

The canonical failure: replace versus extend

This is the one that made us build tooling, and it is described in more detail in the first post on this blog.

Two sessions, two worktrees, one repository:

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

Agent A moves every caller onto the new Stripe class. Agent B adds PayPal to the old class. They touch different files. Git merges both branches without complaint. The PayPal work now hangs off a class nothing calls any more.

Neither agent did anything wrong. Each did exactly what it was asked, each branch passes its own tests, and each agent reports success. Two agents can each be correct and jointly wrong.

Same file is not the same as collision

The intuitive fix is to warn whenever two agents touch the same file. Our own data says that signal is weak in both directions.

When we replayed 76 intents from our own parallel work on GPTree through Foremerge 0.4.0, one pair of branches produced a real Git conflict, and Foremerge had flagged that pair. Five other pairs had changed the same file while both pieces of work were open, and merged cleanly when we checked them with git merge-tree thanks to Foremerge.

What it does show is the shape of the problem. Same-file overlap produced mostly clean merges. The replace-versus-extend failure above produces no file overlap at all. File paths are the wrong unit for the collisions that cost the most.

The replay also showed a real gap: 0.4.0 could not match a scope on a whole class against a scope on one of its methods. Scope hierarchy is a candidate for a later release and is not built yet. More on that in the limitations section below.

How to split work between parallel agents

This part is useful whether or not you ever install anything. Most semantic conflicts are avoidable at assignment time, if you assign on the right axis.

Split by what a task changes, not by what it is called. "Payments refactor" and "PayPal support" sound like different features and change the same class. Before starting a task, ask which things it will change: which classes, endpoints, tables, config keys. Two tasks with no overlap there can run in parallel. Two with overlap need an order.
Name the operation, not just the target. Adding to something, extending it or modifying it preserves what other work depends on. Replacing, removing, renaming or migrating it does not. Two additive tasks on one target usually just need a shared contract. A destructive task on a target anyone else is touching should run alone, or first.
Specify the contract before you split the work. If two tasks meet at a boundary, make one small change that defines the boundary (the interface, the schema, the API shape), merge it, and then start both agents from that commit. In the payments example, that is a PaymentProvider interface first, then Stripe and PayPal implementations behind it.
List the shared registries. Route files, .env.example, dependency manifests, migration numbering, feature flag lists. Almost every task touches one of them, and almost no plan mentions them. In our replay, two of the same-file pairs were exactly this: a routes file and an example env file that neither plan had named.
Write the plans down where every agent can read them, before any code. A shared markdown file listing each agent's task and targets catches duplicate work, as long as every agent reads it every time. It does not catch replace versus extend unless someone reads both entries and notices.
Verify the merged result, not each branch. Every branch can be green while the merge is red. Build, typecheck and test after integration, and treat a branch passing its own tests as a statement about that branch only.
Run only as many agents as you can follow. We do not have a number to give you. The honest limit is how many plans you can read and compare before the agents finish.

Steps 1 to 5 are all versions of one idea: get each plan into a form that can be compared with the others before code exists. That is exactly the step that falls apart past two or three agents, because a person has to do the comparing.

The part Git cannot see: compare plans before code

Foremerge is the tool we built for that comparison. It is an open-source coordination protocol for coding agents that sits above Git. Each agent declares what it is about to change, and how, before it changes anything. Foremerge compares declarations from every agent in the repository and reports a finding when two plans collide, while both worktrees are still clean.

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 kinds are symbol, api, schema, config, infra, test, migration, env, file, component, contract and domain. The operation is declared by the agent rather than guessed from the summary, so "consolidate payments onto Stripe" and "replace PaymentService with Stripe" reach the same verdict.

When Agent B declares symbol:PaymentService=extend, Foremerge raises a destructive_vs_additive finding at HIGH severity, explains that one intent replaces the scope the other extends, and suggests coordinating on a stable PaymentProvider contract first. The suggestion is labelled as a heuristic, not an architecture decision. The response also lists the other agent's intent and every overlapping scope with both declared operations, so the agent can decide what the overlap means and record that decision.

A few properties matter for parallel Claude Code work specifically:

It works across worktrees. The store is a SQLite file inside your repository's Git common directory, which every linked worktree shares. Agents keep isolated files and see the same declarations.
It works across tools. Claude Code, Codex and Cursor each connect through the same MCP server and read the same store, so a Codex session and a Claude Code session on one repository see each other's plans.
You can check before you commit to a plan. check_conflicts runs the same comparison as publishing and stores nothing, so an agent that is still planning can ask without leaving a trace.
Claims never lock. Two agents can claim the same scope. The second gets a warning and the other agent's context, not a refusal, because a lock serializes work that was often compatible.
Acceptance is gated on evidence, not on the agent's word. When an agent finishes, it publishes a ChangeSet, and Foremerge runs a check you registered (a build, a typecheck, a fast test target) against the exact fingerprint of that candidate. An agent saying "tests pass" is recorded as provenance and does not satisfy the gate.

None of this replaces worktrees. Worktrees isolate files. Foremerge shares plans. You want both.

Setting it up

The fastest path is to paste this into Claude Code, Codex or Cursor from inside the repository:

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.

Change step 4 to your repository's real test command. Step 3 asks the client to enable an MCP server, so it will prompt you first.

To install by hand instead: the install script above fetches a checksum-verified release binary for macOS or Linux. npm install -g foremerge works on macOS and on Linux with glibc. cargo install foremerge builds it with Rust 1.85 or later. Windows binaries are on the releases page. Then run foremerge init and foremerge setup claude (or codex, cursor, all) inside the repository.

What it does not catch

A coordination tool that overclaims is worse than none, because severity is what an agent uses to decide what to stop for. So, plainly:

Under-declaration. An agent that declares extend and then rewrites the thing is not detected. Not caught, but auditable: the declaration and the diff are both on record, so the miss can be reconstructed afterwards.
Scope hierarchy. A scope on a whole class does not match a scope on one of its methods, and domain:payments does not imply every payment symbol. Narrow, accurate scopes matter.
Files nobody declared. File overlap is not a conflict signal in this release. The shared registries from step 4 above only show up if an agent declares them.
Synonyms. Two agents using different names for the same concept can slip past the detector, and it can warn on work that was always compatible. Detection is deterministic and explainable, but heuristic.
Late arrivals. A conflict is detected when the later intent publishes. There are no push notifications, so the earlier agent learns of it at its next boundary or by checking again.
Other machines. The store is per machine. Coordination between machines is outside the project's scope.
Measured results. There is a benchmark plan and a harness in the repository, but no published coordinated-versus-uncoordinated results. We make no claim about time saved right now.
Everything else in your pipeline. It does not replace code review, CI, or architecture ownership. A missing finding never proves two changes are compatible.

The full list is in docs/limitations.md.

If you are deciding whether you need this at all, the companion piece on orchestrators and coordinators has a one-question test, and the case for a coordination layer has a post of its own.

Frequently asked questions

Can I run multiple Claude Code sessions in the same directory?

You can, but they share one set of files, so one session's edits and installs land underneath the other's work. Give each session its own Git worktree with claude --worktree <name> or git worktree add. Each gets a separate checkout and branch while sharing the repository's history.

Do Git worktrees prevent merge conflicts between agents?

No. Worktrees stop agents from overwriting each other's files while they work. Textual conflicts still appear at merge time when two branches change the same lines, and semantic conflicts, where two changes contradict each other without touching the same lines, merge cleanly and are not reported at all.

Why did my agents' branches merge cleanly but the app broke?

Most likely a semantic conflict: one agent renamed, replaced or removed something another agent was still using, or changed a schema or config contract the other coded against. Git only compares changed lines, so contradictory plans in different files merge without complaint. Building and testing the merged result catches some of these. Comparing plans before code catches others earlier.

How many Claude Code agents should I run in parallel?

There is no number we can defend. The practical limit is how many plans you can read and compare before the agents finish, plus how many installs, ports and databases your machine can run at once. If tasks change different things, more agents are fine. If they overlap, more agents mostly means more reconciliation.

Does Foremerge work with Codex and Cursor, or only Claude Code?

All three. foremerge setup all installs the skill and MCP entry for Claude Code, Codex and Cursor, and every client reads the same store in the repository's Git common directory. Any other MCP client can launch foremerge mcp over stdio. Agents from different vendors see each other's declared plans.

Does Foremerge lock files or stop agents?

No. Claims are leased and advisory: overlap produces a warning and the other agent's context, never a lock. Findings are evidence for the agent or person to act on. The one hard gate is acceptance, which requires a passing registered check on the exact candidate and no unresolved HIGH finding unless someone overrides it with a recorded reason.

If you run more than one agent

If you only ever run one coding agent, you do not need this. If you run two or more on one repository, worktrees handle the files and Foremerge handles the plans: one Rust binary, local-first, Apache-2.0, with its SQLite store in the Git directory your worktrees already share.

Repo and docs: github.com/naw103/foremerge
Install: foremerge.com

It will miss what agents do not declare. If you hit a collision it should have caught, an issue describing it is the most useful thing you can send us.

Originally published at foremerge.com.

Did you make copies of your custom GPTs?

Nick Woodhead — Sat, 17 Oct 2026 03:21:44 +0000

Nick Woodhead

Oct 14

Gemini Gems become skills in November and custom GPTs retire on December 11. What to copy out first.

#ai #productivity #chatgpt #gemini

4 min read

Translating Technical Debt

Nick Woodhead — Sat, 17 Oct 2026 03:20:01 +0000

What technical debt actually means, and how to explain it to someone who doesn't write code

An engineer asks for two sprints to "pay down technical debt," and the person who owns the budget hears two sprints with nothing to show for them. The phrase was invented to make exactly this conversation easier, and a lot of the time it now gets in the way.

The fix is not a better slide. It's going back to what the metaphor meant in the first place, because the original version already contains the answer to the question the business side is really asking: is this worth paying for?

Where the phrase came from

Ward Cunningham coined it in 1992, in a short experience report for the OOPSLA conference about WyCash, a portfolio management system his team built. The line most people know is "Shipping first time code is like going into debt." The same paragraph says a little debt speeds development, as long as it is paid back promptly with a rewrite, and that the danger is debt that never gets repaid.

In a later video (the transcript is on the c2 wiki) Cunningham explained why he reached for a money metaphor at all. WyCash was financial software, and he needed to explain to his boss why the team kept reworking code that already worked. As the team learned how the financial objects really behaved, they changed the program to match that understanding. If they had not, he said, they would keep stumbling over the gap between what the code said and what they now knew, and that stumbling would slow them down the way interest slows down a loan.

So the original idea is simple. You ship before you fully understand the problem, because shipping is how you learn. Then you put what you learned back into the code. Skip that second step for long enough and every change gets slower.

What it does not mean

In the same video, Cunningham said many people had confused the metaphor with the idea of writing code badly on purpose and cleaning it up later. He was clear that he never favored writing code poorly. What he favored was code that reflects your current understanding, even when that understanding is partial, written cleanly enough that you can change it once you know more.

That matters for the conversation. When an engineer says "we have technical debt," the business side often hears "we cut corners" or "we did it wrong." Usually it means something closer to "we know more now than we did when we built this, and the code has not caught up." That is not a failure. It is what learning looks like in software.

Principal and interest, in plain terms

Martin Fowler's explanation on his site is the clearest one I know of, because it uses the two parts of a loan that everyone already understands.

The principal is the cost of cleaning the code up.
The interest is the extra effort every new change costs while the mess is still there.

His example: a confusing structure means a new feature takes six days instead of the four it would take with a clean structure. Those two extra days are the interest. Cleaning up the structure would take five days.

If that is the only feature coming, cleaning up is a bad deal. Fowler points out you would spend nine days instead of six. But if two more similar features are on the way, cleaning up first makes the team faster overall. Using his numbers: three features without the cleanup is 18 days, and the cleanup plus three faster features is 5 + 12 = 17 days.

Look at what that decision depends on. Not on how ugly the code is, but on how much more work is coming through that part of the system. Engineers know the interest rate. The business side knows the roadmap. Neither can make the call alone.

Not all debt is the same kind

Fowler also sorts debt into a simple grid. One axis is whether the debt was deliberate (you knew you were taking a shortcut) or inadvertent (you found out later). The other is whether it was prudent (taken on with the cost weighed against the benefit) or reckless (taken on without weighing anything).

In plain terms:

Deliberate and prudent: "We took a shortcut to hit the launch date, and we knew it would cost us later." This is a business decision that worked as intended. The bill is now due.
Inadvertent and prudent: "Now that we have built it, we understand how it should have been built." Fowler says even the best teams end up here, because you learn as you go. This is Cunningham's original meaning.
Deliberate and reckless: "We knew better and skipped it anyway to go faster." This usually comes from underestimating how soon the shortcut would start costing time.
Inadvertent and reckless: "We didn't know what good looked like." This is a skills conversation, not a debt conversation.

Fowler's point is that the useful question is not whether a team has debt, since every team does, but whether it was prudent or reckless. Knowing which kind you are talking about tells you whether this is a normal bill, a lesson, or a problem with how the work is done.

If you write the code: how to explain it

The goal is to give the person with the budget something they can decide on. A few habits help.

Lead with the interest, not the principal. "We need two sprints to refactor billing" is a cost with no benefit attached. "Every change to billing takes about two extra days because of how it is structured" is a cost they are already paying. Use your own real numbers, even rough ones.
Connect it to work that is actually coming. Name the upcoming items on the roadmap that go through that part of the system. If nothing is coming, say so. Leaving it alone can be the right call, and saying that out loud earns you trust for the times it is not.
Show the payback. Cleanup cost, the time each change saves, and how many changes until it pays for itself. Fowler's example is a good template because the arithmetic fits on one line.
Say which kind it is. "We took this shortcut on purpose to make the March launch" lands very differently from "this is how we learned the problem." Both are fine. Just say which.
Ask for a decision. End with the options and what you would pick: pay it now, pay it before a specific feature, or leave it. Do not end with "let's discuss."

If you fund the work: how to ask about it

Business leaders can make this conversation easier too.

Ask "what does this slow down, and by how much?" instead of "why is the code bad?" The first question gets you an interest rate. The second gets you a defensive answer.
Ask "what happens if we never pay it?" Sometimes the honest answer is "nothing much, that area rarely changes," and that is useful to know.
Share what is coming. The engineers can only work out whether the cleanup pays back if they know what the next few months of work look like.
Treat a debt request as information, not an admission. The team is telling you about a cost you are already paying.

One question that carries most of it

Every version of this conversation comes down to one question both sides can answer together, what is the interest on the work we are about to do? Explaining tradeoffs in terms like that, so the decision happens in the meeting, is what TranslateTech's Geek2Speak series is about.

Next time technical debt comes up, ask (or answer) that one question before anyone talks about how long the cleanup takes.

[Boost]

Nick Woodhead — Wed, 14 Oct 2026 06:27:24 +0000

Nick Woodhead

Oct 14

Gemini Gems become skills in November and custom GPTs retire on December 11. What to copy out first.

#ai #productivity #chatgpt #gemini

4 min read

Gemini Gems become skills in November and custom GPTs retire on December 11. What to copy out first.

Nick Woodhead — Wed, 14 Oct 2026 06:23:48 +0000

If you built a Gem in Gemini or a custom GPT in ChatGPT, it is about to be converted into something else on the vendor's timetable, not yours. Both companies say most of it carries over, but both also list things that do not, and those are the parts you will miss the next time you use it.

I read both help pages today (October 13, 2026). Here is what each one says, what does not make the trip, and what I would copy out this week.

What Google says about Gems

Google's help page "About the transition from Gems to skills" says that starting in November 2026, Gems will transition to skills for personal Google Accounts, and in 2027 for work and school accounts. The page gives March 2027 for Workspace business accounts and June 2027 for education accounts.

When Gems are removed, Google says it will automatically recreate your Gems as skills, along with supported knowledge files. A skill is a set of reusable custom instructions you call by typing a slash and its name in any Gemini chat, and Gemini can also apply one on its own when it thinks it is relevant.

The same page lists what is different:

Skills do not work with Canvas or Deep Research yet, and most of the default tools a Gem could use (Create video, Create music, Guided learning) are not available to a skill.
Files a Gem pulled from GitHub are not supported in skills, so they are not converted.
Sharing a skill, and adding Google Drive files to one, are listed as coming in the coming weeks.
You can make as many skills as you like but only 100 can be active at once.

So a Gem that was mostly instructions will be fine. A Gem that leaned on Canvas, Deep Research, a GitHub file or a share link to your team will come out the other side missing a piece.

What OpenAI says about custom GPTs

OpenAI's "Custom GPT retirement and migration FAQ" says custom GPTs are scheduled to retire on December 11, 2026 (February 11, 2027 for Enterprise workspaces with an approved deferral), and that the change affects all ChatGPT plans. Creators migrate each GPT to a plugin from My GPTs when the option shows up for their account.

What transfers, per the FAQ: the GPT's instructions become a skill inside the new plugin, connected apps are added as apps, and knowledge files are copied into the plugin's reference files. Your existing conversations with the GPT stay accessible after retirement.

What does not:

The GPT's selected model does not carry over.
Custom actions do not transfer. The FAQ says rebuilding one may need a custom MCP server.
Sharing settings do not carry over. A migrated plugin starts private, and the people who used your GPT do not get access to the replacement automatically.
Migration uses the latest published version, so drafts and unpublished edits are left behind.
After you migrate, the original GPT becomes read-only.

OpenAI also says plainly that a migrated plugin may respond differently, and suggests saving a few familiar prompts so you can compare the results before and after.

The pattern in both

The two migrations are not the same, but the same three things hold in both.

The instructions survive. In both cases the text you wrote is the part that converts cleanly.

The wiring does not. Tools, actions, model choice and sharing are the parts each vendor is changing, and they are the parts you cannot export as text.

You do not pick the date. Google gives a month, OpenAI gives a day, and both pages say the timing can differ by account.

That tells you where the work is. The instructions are the asset, and a copy of them in a plain file is worth more than whatever container they sit in this quarter.

What I would copy out this week

This takes about 20 minutes for a handful of assistants.

Open each Gem and each GPT you still use and paste its name, description and full instructions into a text or markdown file. One file per assistant.
Download the knowledge files into the same folder. Google's own steps for recreating a Gem as a skill start with exactly this.
Write down what it depended on that is not text: which model, which tools (Canvas, Deep Research, actions, connected apps) and who it was shared with.
Save three or four prompts you run often, with an answer you were happy with. OpenAI recommends this for testing a migrated plugin and it works just as well for a skill.
If a GPT has unpublished edits you care about, publish them before you migrate. Publishing does not require sharing it publicly.
After the conversion, run the saved prompts and compare. Fix what changed before you rely on it.

One useful detail on the Google side: the help page says you can upload a SKILL.md file to bring in a skill made on another platform, in the Gemini web app and Mac app for now. OpenAI's migration also turns your instructions into a skill. Both vendors are converging on instructions kept as a file, which is one more reason to keep your own copy as one.

Where GPTree fits

I built GPTree, so read this part knowing that. GPTree does not import Gems or GPTs. What it has is personas, and a persona is three plain fields: a name, an optional description, and the instructions. The text you copied out in step 1 pastes straight into the instructions box. You pick a persona per message from the composer, and personas apply per branch, so you can send the same question down two branches under two personas and compare the answers. On the Free plan you can keep one persona of your own, and the built-in ones do not count toward that.

That is not a migration tool and I am not selling it as one. The point of the list above is the same wherever you paste the result.

The next step

Pick the one Gem or GPT you would miss most, and copy its instructions and files into a folder today. Everything else on the list can wait until the migration option shows up in your account.

AI agents introduced several new layers to the development stack. You are probably missing this one.

Nick Woodhead — Thu, 17 Sep 2026 01:39:19 +0000

The development stack grew more in the last two years than in the previous ten. Most teams adopted the new layers so quickly they never noticed them becoming layers. Count them.

The agent layer: Claude Code, Codex, Cursor. The thing that writes code. Two years ago this layer did not exist; today it is where implementation happens.

The context layer: CLAUDE.md, AGENTS.md, rules files, memory systems. Telling agents how your repository works, what your conventions are, what not to touch. Everyone who onboarded an agent wrote these within a week, because an agent without context is a very fast junior with amnesia.

The tool layer: MCP. Agents reaching databases, browsers, issue trackers, deployment systems. Adopted fast because an agent that cannot touch your systems can only talk about them.

The isolation layer: git worktrees, containers, cloud sandboxes. One agent per checkout, because two sessions in one working directory stomp each other's files and poison each other's context. Anyone who ran two agents learned this in the first afternoon.

The orchestration layer: Gas Town, claude-squad, Foreman, and a fast-growing ecosystem of fleet runners. Who works on what, which sessions are alive, what needs review. The moment you run more than two or three agents, supervision becomes its own job, and this layer takes it.

Each of these layers got adopted quickly for the same reason: its absence hurts immediately and obviously. No context, the agent writes nonsense today. No isolation, files get stomped today. No orchestration, you lose track of your fleet today.

There is one more layer, and almost nobody runs it, because its absence hurts silently.

The failure that announces nothing

Two agents, one repository. Agent A is told to replace PaymentService with a Stripe-specific implementation. Agent B is told to add PayPal support to PaymentService. Run the failure through every layer you have adopted.

The agent layer performs perfectly: both sessions write competent code. The context layer performs: both followed your conventions. The tool layer performs: every MCP call succeeded. The isolation layer performs: separate worktrees, no stomped files. The orchestration layer performs: two independent tasks, both completed, both green.

Git merges both branches without a conflict, because the changes touch different lines. And the design is now broken: agent B built on an extension point agent A deleted. Nothing in the toolchain objected at any moment, because every layer you have answers a different question, and none of them answer this one: can these two plans coexist?

Git compares diffs, and there is no diff at the moment this collision actually happens. The collision is between intentions, at plan time, before either agent has written a line. We hit versions of this for months. The one that finally made us build tooling surfaced three days after a clean merge, in production.

The coordination layer

The missing layer answers exactly one question: can the work currently in flight all be true at once?

To be precise about what it does not do: it does not create plans. Your agents plan however they already plan. The coordination layer is a ledger and a referee, not a planner. Each agent declares what it is about to change before writing code: a semantic scope plus an operation, like symbol:PaymentService=replace. Scopes are not file paths, because file paths miss API, schema, configuration, and cross-language collisions. Deterministic rules compare the declarations and raise a finding while both sides are still plans: the rule that fired, an explanation, a suggested resolution. In the PaymentService case, one destructive operation and one additive operation on the same scope cannot both be true, and the second agent learns this in the same call that published its intent.

The other half of the layer is evidence. When work finishes, acceptance is gated on a verification command the layer executes itself against the exact fingerprint of the candidate change. An agent reporting that tests pass is provenance, not proof. If the tree changed after validation, the attempt does not count.

What building one taught us

Three lessons, each paid for.

First: declared beats inferred. We started by inferring operations from agent prose, and it produced confident false alarms. "Delete the flaky ThumbnailCache benchmark test" was read as destroying ThumbnailCache itself. Widening the verb list just moved the boundary. Making agents declare the operation as structured syntax removed the whole error class.

Second: advisory beats locks, but severity must be earned. Most overlaps between agents are compatible, and a lock serializes work that did not need serializing; the moment a lock exists, a busy repo becomes a queue. So claims warn instead of block. The discipline that makes warnings survivable is reserving HIGH for two declarations that genuinely cannot both be true. Our repo carries a regression fixture that fails the build if compatible work ever raises a HIGH.

Third: soft claims, hard gate. Everything before the finish line is advisory, because the finish line is not: no acceptance while an unresolved HIGH finding stands, and no acceptance on self-reported evidence. The gate staying hard is what lets everything before it stay soft.

Do you need this layer?

If you run one coding agent, no. Close the tab, you are fine.

If you run two or more on the same repository, whether in parallel today or sequentially across days, you have already had the silent version of this failure whether you noticed it or not. The tell: a change that made you say "wait, when did that class stop existing?" three days after a clean merge.

We open-sourced the coordination layer we built and use: Foremerge (https://github.com/naw103/foremerge), Apache-2.0, one Rust binary, local-first, above Git rather than inside it. Setup is one paste into Claude Code, Codex, or Cursor. Stated plainly per the honesty its own docs demand: detection is deterministic but heuristic and can warn on compatible work, claims never lock anything, and there are no published benchmarks yet, so no performance claims. The layer matters regardless of whose implementation you run, including one you build yourself.

The stack grew five layers in two years because each one's absence hurt the day you needed it. The sixth one's absence hurts three days later. That is the only reason you are probably missing it.

Foremerge
The open-source coordination protocol for parallel coding agents, built above Git. Agents declare intent and semantic scopes before writing code, so plans that cannot both be true collide in a queryable store instead of in your merge. One Rust binary, Apache-2.0, local-first.

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