DEV Community: Nick Woodhead

[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

Any thoughts on this?

Nick Woodhead — Thu, 17 Sep 2026 01:32:04 +0000

Nick Woodhead

Sep 4

31 hard questions about coordinating parallel coding agents, answered

#ai #opensource #git #rust

11 min read

Both words mean "make several agents work together," so they get used interchangeably. They name different layers, and one question tells you which one you are running.

Nick Woodhead — Mon, 14 Sep 2026 05:06:30 +0000

Nick Woodhead

Sep 14

Agent orchestrators and agent coordinators are not the same layer

#ai #devtools #opensource #git

6 min read

Agent orchestrators and agent coordinators are not the same layer

Nick Woodhead — Mon, 14 Sep 2026 05:05:29 +0000

If you only ever run one coding agent, you do not need either of these. Close the tab, you are fine.

For everyone else: I maintain Foremerge, and I recently submitted it to a list called awesome-agent-orchestrators. It was merged into a section for infrastructure and coordination protocols, which is the right shelf. The list's name is still the wrong noun for it. Foremerge is not an orchestrator. It cannot start an agent, cannot stop one, and does not know when one is running. Coordination currently lives as a shelf inside an orchestration list, which says a lot about how new the distinction is.

The two words get used interchangeably, and reasonably so. Both mean something like "make several agents work together." But they describe different layers of the stack, with different authority, different failure modes, and different reasons to exist. Here is the difference, and a one-question test for telling them apart.

The test

What happens if you kill it?

Kill your orchestrator and the fleet stops. Sessions die, queued work never starts, nothing is spawned or resumed until you bring it back. An orchestrator sits in the control path.

Kill your coordinator and every agent keeps typing. You lose the shared picture, not the work. A coordinator sits beside the control path, not in it.

That single structural fact drives everything else about how the two behave.

What an orchestrator does

It owns the run loop. Concretely: spawning sessions, placing each one somewhere isolated (a worktree, a container, a cloud sandbox), deciding what runs next and in what order, restarting what died, routing prompts and results, and giving you one screen showing which of your fourteen sessions are alive and which are waiting on you.

This is real work and it becomes its own job the moment you pass two or three agents. The ecosystem here is growing fast and includes both standalone session managers, claude-squad, dmux, amux, agent-deck and their neighbors, and in-session fan-out inside a single agent, like Claude Code's subagents or a workflow script that runs a dozen tasks in parallel.

An orchestrator's authority is imperative. It can start things and stop things. Its input is tasks. Its state is sessions and processes. Its question is who is running what right now?

What a coordinator does

It never starts or stops anything. Its input is not tasks but declarations: before an agent edits, it states what it is about to change, in a form precise enough to check.

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

A scope is not a file path, because file paths miss API, schema, configuration and cross-language collisions. The operation (replace, extend, and the rest) is declared rather than parsed out of the summary. When a second agent declares symbol:PaymentService=extend, deterministic rules compare the two declarations and return a finding in the same call that published the second intent. This is real 0.4.0 output, captured while writing this piece:

{
  "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.",
  "evidence": {
    "rule": "FM-C001",
    "source_operation": "extend",
    "target_operation": "replace",
    "source_operation_inferred": false,
    "target_operation_inferred": false,
    "detected_before_code": true
  }
}

Note what is absent. No process id, no session, no queue position, no instruction to either agent. The coordinator does not know whether either agent is currently running, and does not need to. Its question is can the work in flight all be true at once?

Its authority is evidentiary rather than imperative. It cannot stop a keyboard. What it can do is withhold its blessing at the end and say exactly why:

BLOCKING_CONFLICT: 1 unresolved HIGH intent conflict(s);
coordinate and resolve them before acceptance

CHECK_FAILED: this ChangeSet is UNVERIFIED (no verification check was
run against this ChangeSet)

Both are overridable, by a human, with a recorded reason. That is the shape of evidentiary authority: it can make you look, it cannot make you stop.

The split, in a table

	Orchestrator	Coordinator
Owns the run loop	Yes	No
Authority	Imperative: start, stop, schedule	Evidentiary: findings, gates, audit
Input	Tasks	Declared intents and scopes
State	Sessions, processes, queues	Intents, claims, findings, changesets, validation
Question answered	Who is running what?	Can these plans coexist?
If it dies	The fleet stalls	Agents keep working, you lose visibility
Visibility scope	Its own sessions	The repository, across sessions and vendors

Three consequences worth caring about

One: an orchestrator can only see its own fleet. It knows about the sessions it spawned. Your actual working day is Claude Code in one window, Codex in another, Cursor open on the same repository, plus a colleague, plus something you started on Tuesday and came back to on Thursday. Claude Code coordinates its own subagents inside one session, and does it well, because there is one root and one plan. Between roots, nothing does. A coordinator earns its keep by being neutral about who spawned the agent, which is also why one built into a single runner would see less.

Two: an orchestrator's only lever is scheduling. If the only tool you have is control over execution order, then your only conflict resolution is serialization: run them one at a time and the collision cannot happen. That is correct and expensive, because most concurrent work on a repository is compatible and did not need serializing. A coordinator can let both agents run and raise a finding, precisely because it is not responsible for the run loop.

Three: being outside the control path forces a design choice. A coordinator must never lock, because a single crashed agent holding a lock would stall the fleet, which is the exact failure it was supposed to help you avoid causing. So claims are leased and advisory: overlap produces a warning and shared context, never a lock. What makes advisory claims survivable is that the last step is not advisory. No acceptance while an unresolved HIGH finding stands, and no acceptance on an agent's own report that tests passed. Soft claims, hard gate.

Could one tool be both?

Structurally, yes, and nothing stops it. An orchestrator could grow declared scopes and deterministic comparison rules and cover both layers in one process. Most of the tools on that list manage sessions and worktrees, which is what they set out to do, and its infrastructure section already carries a few coordination tools, this one included. What I have not yet seen is a single tool that runs the agents and also compares declared operations before code exists.

The interesting part is what such a tool would have to add, because it is not just a feature. An orchestrator holds prompts. A prompt is prose, and inferring an operation from prose produces confident false alarms: we tried it, and "delete the flaky ThumbnailCache benchmark test" got read as destroying ThumbnailCache itself. Widening the verb list only moved the boundary. Asserting HIGH severity on a guess is how a coordination tool gets ignored in a week. A declared operation is a fact, and facts are what a rule can be strict about. In 0.4.0 only declared operations can assert HIGH; prose-inferred matches cap below it.

So the question is not whether one process can hold both layers. It is whether it holds declarations or just prompts.

Which one do you need?

One agent: neither.

Two or three in parallel: orchestration first. Its absence hurts today, in ways you notice within an afternoon. Lost sessions, stomped files, no idea what is still running.

The coordination layer's absence hurts on a delay. Both agents finish, both look right, Git merges both without a conflict because nothing textually overlaps, and three days later you are asking when that class stopped existing. That is the failure that made us build this one.

Foremerge is the coordination layer we extracted from the monorepo of internal tools we use building GPTree, and open-sourced in late August 2026. One Rust binary, Apache-2.0, local-first, a CLI plus a local JSON API plus an MCP server over one SQLite store inside your repository's Git common directory. It sits above Git rather than inside it, and it composes with whatever orchestrator you already run.

Stated plainly, per the honesty its own docs demand: detection is deterministic but heuristic, so it can warn on compatible work and can miss incompatible plans when agents name the same concept differently. Claims never lock anything. Agent identity is self-asserted, so the ownership guards raise the bar against confusion, not against a caller that deliberately presents another agent's id. It is local-only today, with no multi-machine mode. There are no published benchmarks yet, so there are no performance claims here.

The layer matters regardless of whose implementation you run, including one you write yourself. So here is the noun test one more time. If it can start and stop your agents, it is an orchestrator. If it can only tell you whether their plans can coexist, and refuse to bless the result at the end, it is a coordinator. Most fleets run the first. Almost nobody runs the second.

[Boost]

Nick Woodhead — Fri, 04 Sep 2026 05:39:26 +0000

Nick Woodhead

Sep 4

31 hard questions about coordinating parallel coding agents, answered

#ai #opensource #git #rust

11 min read