Claude Code context reconciliation, two problems hiding under one phrase.

Problem 1: token-window compaction. Mostly solved.

Compaction is the part of “reconciliation” that has a real, named, platform-level mechanism behind it. The shape of the feature is well documented and stable. When the input token count approaches the configured trigger for the active model, the runtime takes the older turns of your conversation, generates a summary, wraps it in a <summary>...</summary> tag, and replaces the older raw turns with that single block. The response continues from the compacted state.

The reason this rarely surfaces as a real production bug is that the platform is the only writer to this state. Nothing else on your machine can mutate the conversation transcript. The trigger, the summary, and the resumed history all live inside one process. If you want visibility into where your tokens are sitting, the /context command in Claude Code prints the breakdown: system prompt, tools, memory files, skills, conversation history. If you want to compact early on purpose (for example before a long multi-tool stretch where you want fresh headroom), /compact triggers it manually.

The one nuance worth knowing: compaction summarizes in-context state. If a load-bearing fact for a future decision lives only inside a tool output you read twenty turns ago (a directory listing, a SQL row count, a config diff), the summary may compress it to nothing. The fix is mechanical: any time you depend on a fact that lives in a transient tool output, write it down into a CLAUDE.md note or a task scratch file. That copy survives compaction. The original turn may not.

Problem 2: world-state reconciliation. Where the bugs actually live.

Compaction has one writer. World state has many. While Claude Code is in the middle of a task, every one of these can move the truth out from under it without telling it:

• You save a file in your editor, fixing the typo Claude was about to fix.
• A teammate pushes a commit to main that conflicts with the branch Claude is working on.
• A pre-commit hook reformats the code Claude just wrote, so the next Read shows different bytes than the Edit produced.
• A second Claude Code session, running in another worktree, edits the same file at the same time.
• A cron job auto-commits and pushes uncommitted work every minute. The diff Claude was reading from git diff is gone by the time it tries to act on it.

None of those raise an exception inside Claude Code. They just silently invalidate the agent's mental model of the world. The agent's next Edit, written against the stale picture, is the bug. This is what people are reaching for when they say “context reconciliation” and mean something different from /compact.

The platform's own primitive: Read-before-Edit

The most underrated thing in Claude Code is that the Edit tool refuses to run if you have not Read the file in this session. The tool description spells it out: You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. When you violate it, the runtime returns the same error, by name, every time:

That contract is the platform's native world-state reconciliation primitive. It forces the agent to materialize the current bytes of the file into context before proposing a diff. Most failure cases people blame on “reconciliation” are cases where this primitive is either disabled (some third-party agent frameworks let you Edit without first Reading) or technically satisfied but stale (the Read happened ten minutes ago, before another writer touched the file).

Naive workflow vs. reconciliation-aware workflow

The before/after below is the actual delta between a session that ships a broken commit on a busy repo and a session that does not. Both use the same tools. The difference is purely in when you re-materialize state.

Five reconciliation patterns I put in every CLAUDE.md

These are not theoretical. They are the lines I add to client CLAUDE.md files when I scope an agent rollout. Each one is a workflow rule the model picks up on session start, so the cost of compliance is paid once at write time, not per turn.

What does the diff between “trust memory” and “reconcile” look like in practice?

Two snippets, same task, both in the same Claude Code session on the same repo. The left is what the agent does naturally if you do not ask it to reconcile. The right is what it does if you put the rules above in CLAUDE.md.

# remembered Read from minute 0
Edit("src/app/api/route.ts", { ... })
Bash("npm test")
Bash("git add -A")
Bash("git commit -m 'wire up endpoint'")
Bash("git push")

The right column adds 5 cheap calls. Two of them are pure-read git calls (no I/O on the working tree). The other three are a Read of one file plus two narrower git operations. It is a few thousand extra input tokens, which on a cached prompt is fractions of a cent. The bug it prevents is “commit includes a revert of a change you did not write,” which is the actual production failure mode of agentic coding on shared repos.

Counterpoint: when the doc-based advice is enough

The /compact and /context advice that fills most of the existing material on this topic is genuinely sufficient for a real subset of users. If you are the only writer to the repo, do not have background agents running, and your sessions are short, the platform's built-in behavior covers you. Compaction will handle long sessions. The Edit tool's Read-before-Edit contract will catch the cold-start case. You probably do not need five workflow rules in your CLAUDE.md to ship safely.

Where the existing advice runs out is the moment a second writer shows up. That is most of my client work: SMB teams where the engineer is using Claude Code, a teammate is pushing on the same branch, a formatter runs on save, a cron is auto-committing, and a second agent is open in another worktree. In that environment the world-state side of reconciliation becomes the dominant source of bugs, and /compact is irrelevant to all of it.

What this looks like as a c0nsl engagement

For most teams the work to fix this is a CLAUDE.md rewrite plus two or three repo conventions, which fits the published $500 to $2,000 small integration tier on the homepage. For teams running multiple agents in parallel, custom tool wrappers, or a self-hosted Claude SDK setup, the right shape is closer to the $2,000 to $10,000+ custom system tier: a real audit of every place state can drift, an updated tool contract, and an eval harness that exercises the multi-writer cases. Either way, the rate is on the page, the scope is named up front, and the deliverable is a repo that does not ship a broken commit because two writers disagreed about what was on disk.