One sub-agent rewrote the plan. The other kept coding against the old one.

Running parallel Claude Code or Codex sessions on one repo?

This page covers sub-agents inside one graph, sharing state through the store. Separate coding-agent sessions — parallel Claude Code tabs, a Codex worker next to your editor, a worktree orchestrator — are separate processes. The same coordinator reaches them three other ways:

One session overwrote another's plan.md? Your auto-fix bot fired a build on a config that had already moved? Those are the failure shapes these three close — on one host.

Why this exists.

The artifacts your agents write, deliberately. Retrieval keeps agents fresh on what the world writes — indexes, knowledge graphs, search. agent-coherence covers the other direction: keeping agents consistent with each other on the artifacts they write. On CCSStore the enforcement lands at read time (invalidation). Denying a stale write outright is CoherentVolume and write_cas.

And when you don't need this: if each agent gets its own worktree and nothing is shared — no common plan file, config, or store key — isolation already solves it. Same if your store is append-only: writes never mutate in place, so there's structurally no lost update. agent-coherence is for the must-share surface that survives isolation.

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

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

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

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: python -m examples.refactor_demo.main --variant=context-cache, then --variant=no-invalidation and --variant=with (needs Node ≥18 for the tsc fixture). 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.

And it's cheaper too.

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.

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.

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 a fresh
# miss and pulls v2 — the stale cached copy is never served again.

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. Everything on this page is single-host: one coordinator, one machine. If your agents span hosts, that is an active co-design, not a shipped surface — open a GitHub Discussion or email us.

Two more surfaces shipped in v0.10.0. When a developer or a tool edits a managed shared file out of band — outside the coordinator — that foreign edit is caught the moment an agent writes over it (denied by default) or, opt-in, re-reads it, surfaced as StaleView and cleared with reacquire(). It covers files the volume manages; auto-watching unmanaged corpora is roadmap. 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. Sessions sharing one SWG_ROOT share one coordinator, so session B's stale write is denied even when session A made it stale, and two sessions racing the same file resolve through swg_write_cas: one wins, the loser gets a typed retryable conflict instead of a silent drop. It guards file access routed through the tools — it cannot see edits made around them.

Two adoption tiers.

Pick where on the commitment curve you want to start.

# 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 warns — or in strict mode denies — when your session is about to act on a tracked artifact another session has since changed (CLAUDE.md, plan.md, spec.md, runbooks). It covers the sequential stale-read-then-write hazard; concurrent write arbitration comes via the MCP server, not plugin hooks. See the plugin landing page →