agent-coherence. Book a call

Coding agents · write-side coherence

v0.7.1 · Apache-2.0 · PyPI

Coding sub-agents collaborating on a refactor — without trampling each other's edits.

Cursor's planner-executor sub-agents, Claude Code's sub-task workers, Factory's parallel runs, Opencode's planning loops — they all share state through a task spec. When one sub-agent writes v2 of that spec mid-flight, the others keep operating on v1. agent-coherence detects the moment of divergence and serves the current version on the next read — before any stale commit lands in your repo.

Book a 15-min call → View on GitHub Watch it run ↓
$ pip install "agent-coherence[langgraph]"
12-second looping diagram: t=0 planner writes v1; t=1 executor caches v1; t=2 planner writes v2 and CCSStore invalidates executor's cache; t=3 executor refetches v2; final state tsc passes.
The happy path, in 12 seconds. The op log and real tsc result are in the casts below.

Why this exists.

1

Coding sub-agents stay in sync on the artifacts they write.

The task spec. The plan. The symbol table. The design note. When one sub-agent edits a shared artifact, the others see the new version on their next read — not the version they cached three seconds ago.

2

Coding agents are increasingly multi-agent, and they share mutable state.

Cursor's planner runs while the executor types. Claude Code spawns parallel sub-tasks. Factory fans out across worktrees. Opencode coordinates planning loops. And as of 2026, Anthropic's Agent View productized 10+ parallel Claude Code sessions in a single workspace — Research Preview, no documented state-isolation model. The work is concurrent; the assumption that "what I read is what's current" is implicit, untested, and silently false. agent-coherence makes it explicit and provable.

3

Cache coherence — for the artifacts your agents share.

The protocol every modern CPU uses to keep multi-core caches consistent, adapted for LLM agents that share mutable state. Same primitives: states per (agent, artifact), invalidation on write, single-writer ordering. Same invariants: monotonic versions, no torn reads. Production-tested theory, new application surface.

Write-side, deliberately. Read-side approaches keep agents fresh on what the world writes — indexes, knowledge graphs, retrieval. agent-coherence is the write-side complement: keeping agents consistent with each other on the artifacts they write.

The recorded proof.

Three variants on the same TypeScript refactor. The op log makes the protocol mechanism visible; the tsc result makes the application-level consequence visible. Real terminal output — nothing edited.

1

The failure your agents have today

variant=context-cache · executor never re-reads from the store; commits the v1 it captured at read time. Mirrors LLM context-window behavior. → tsc FAIL

Terminal recording: planner writes v1, executor reads v1, planner writes v2, executor commits cached v1 with 4 files renamed, tsc FAIL with TS2305 error on src/utils/session.ts

2

The protocol-level proof

variant=no-invalidation · same code path, a single-line bus suppression — disable_invalidation(store). Watch the op log: commit-time get is [HIT] (cache stayed SHARED at v1). Same broken build. → tsc FAIL

Terminal recording: same as context-cache but the op log shows [HIT] on the commit-time executor get, proving the cache stayed SHARED at v1; same tsc FAIL outcome

3

With agent-coherence

variant=with · default CCSStore, lazy strategy. Planner's v2 write publishes invalidation before write() returns; executor's next get is [MISS]; refetches v2; commits all 5 files. → tsc OK

Terminal recording: planner writes v1, executor reads v1, planner writes v2, executor's next get is [MISS] and refetches v2, commits 5 files renamed, tsc OK

All three recordings come from examples/refactor_demo/ in agent-coherence v0.7.1+ — real terminal output captured via asciinema and rendered to GIF with agg. Reproduce locally: ./outreach/demo/record.sh all. Source: agent-coherence/examples/refactor_demo.

The exact moment things diverge.

Planner sub-agent and executor sub-agent are working on the same refactor. Both read and write the same shared artifact: a task spec describing what to rename and where.

t=0

Planner writes v1 of the task spec.

"Rename validateUser → authenticateUser. Update 3 callers: middleware.ts, login.ts, refresh.ts."

t=1

Executor reads v1, begins.

Cached locally per the MESI protocol; ready to rename three callers.

t=2

Planner discovers a fourth caller. Writes v2.

"…and session.ts." Coordinator publishes an invalidation event to peers holding the v1 cache — synchronously, before write() returns.

t=3a

Without coherence: executor commits on stale v1.

Three callers renamed; session.ts still references validateUser. tsc fails: "Cannot find name 'validateUser'." Hard build failure, silently introduced by an agent that thought it had the latest plan.

t=3b

With coherence: executor's next read pulls v2.

The cache is INVALID; the next get() refetches v2; executor completes four renames; tsc passes. Prevention, not post-hoc repair.

How it ships into your coding-agent stack.

The task spec is just an artifact in CCSStore — a LangGraph BaseStore drop-in. Both sub-agents share the same store; the MESI protocol does the rest. No node-code changes.

# Coding-agent flow — planner and executor share a task spec via CCSStore
from langgraph.store.memory import InMemoryStore  # before
from ccs.adapters import CCSStore                  # after

store = CCSStore(strategy="lazy")
graph = builder.compile(store=store)

# Planner writes v2; CCSStore publishes invalidation to peers
# before write() returns. Executor's next get() is guaranteed
# to pull the current version — no stale-read window.

The same protocol works on CrewAI and AutoGen via their adapters, and on custom orchestrators via CoherenceAdapterCore. Vendor-neutral across Anthropic, OpenAI, Google, Mistral, and open-source models — the protocol operates on artifacts, not model responses.

Two adoption tiers.

Pick where on the commitment curve you want to start.

Hard

CCSStore — protocol-enforced coherence

Drop-in for LangGraph; adapters for CrewAI, AutoGen, custom orchestrators. Stale reads can't reach commit code because the protocol invalidates peer caches synchronously before write() returns. The fix.

Advisory

ccs-diagnose — passive observation, zero code change

Static analyzer that detects divergent-read risk in existing graphs before any adoption. Reports the artifacts whose reads can be handed stale versions, with line numbers. Triage before commitment.

# zero-network, runs against your existing graph
ccs-diagnose --graph my_graph.py:build_graph

Why this matters now.

Building parallel coding sub-agents that share a task spec?

15-minute call. We'll look at your planner-executor graph and tell you whether agent-coherence will hold up under live re-planning.

Book a call →