agent-coherence. Book a call

Multi-agent code pipelines · coherent shared state

Apache-2.0 · Open source · PyPI

What multi-agent code pipelines look like with coherent shared state.

Subagent fleets reviewing the same codebase. Planner-executor pairs editing a shared task spec. Refactor graphs fanning out across worktrees. When two of them write to that shared artifact, agent-coherence detects the moment of divergence and serves the current version on the next read — before any stale commit lands.

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.

Subagent fleets, by the numbers.

A 4-agent code-review pipeline ships in the repo as a working example. Four reviewer subagents — style, security, architecture, synthesizer — read the same eight files in two passes each through CCSStore. Real LangGraph; deterministic fixture, no LLM API calls.

37.6%
token reduction per run
16,820
tokens saved · 44,702 → 27,882
35.3%
cache hit rate over 51 read ops

Reproduce locally: python -m examples.shared_codebase.main · Source: examples/shared_codebase. This is the as-shipped real-LangGraph number — not the simulation benchmarks elsewhere in the repo.

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 pipelines are increasingly multi-agent, and they share mutable state.

Claude Code spawns Task subagent fleets. LangGraph code-review graphs run three or four reviewers over the same artifact. Refactor pipelines fan out planners and executors that edit a shared task spec. 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 more surfaces shipped in v0.10.0. When a developer or a tool edits a shared file out of band — outside the coordinator — that foreign edit is now caught the moment an agent re-reads it (denied in strict mode) or writes over it (denied by default), surfaced as StaleView and cleared with reacquire(). And if your agents are MCP clients, stale-write-guard-fs (pip install "agent-coherence[mcp]") exposes the same coordinator over stdio — five tools (swg_read, swg_write, swg_reacquire, swg_write_cas, swg_status) — no orchestrator required.

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.

Using Claude Code rather than calling the library directly? The same coherence machinery ships as a Claude Code plugin that injects stale-read warnings into your session when another session has touched a tracked artifact (CLAUDE.md, plan.md, spec.md, runbooks). See the plugin landing page →

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 →