Context compaction — what happens when Claude Code compacts, and why it costs you twice

Definition

Context compaction is what an AI coding agent does when your conversation no longer fits in its context window: it compresses the history into a summary and carries on from that summary instead of the full transcript.

It is a recovery mechanism. A model has no memory between turns, so the entire conversation is re-sent on every turn, and there is a hard ceiling on how much can be sent at once. A long session eventually reaches it. Rather than failing outright, the agent writes itself a condensed account of what happened so far and keeps going from there.

That is genuinely useful, and it is why a long session can continue at all. But it is worth being clear about what it is. Compaction happens after a problem rather than as something you are aiming for, and a session that compacts repeatedly is telling you how much it was carrying.

This is a distinct idea from context efficiency, which is the discipline of carrying only what the task needs. Compaction is the mechanism that fires when that discipline runs out of room.

What it actually costs you

Compaction is not free, and it is not free in three separate ways.

It costs tokens to perform. Summarizing the conversation means reading the conversation. The agent pays to process what it is compacting, and then pays again to carry the summary forward.

It resets your prompt cache. Carried context is normally billed at cache-read rates, roughly a tenth of fresh input, because the provider matches your context as a prefix and reuses what has not changed. A compaction replaces the front of that prefix with a summary, so nothing matches and the whole window has to be written to cache again at above the uncached rate. This is the charge people never see, and on a long session it is the larger of the two.

It costs detail. A summary is lossy by definition. The specific error message from twenty turns ago, the exact reason you rejected an approach, the particular shape of a file the agent read once: some of it does not survive. This is why an agent often feels like it got slightly worse right after compacting. It did not get worse at reasoning, it lost the material it was reasoning over. You then spend more turns re-establishing things it already knew, which costs more tokens, which brings the next compaction closer.

That last cost is the one people misread. "The model got dumber" is almost always "the model lost the context," and the fix is upstream of the model.

Why your window filled up

Compaction is the symptom. The causes are ordinary and mostly habitual:

• Files that never left: everything read early in the session is still being carried at the end, whether or not it is still relevant.
• Re-reads: the agent reading a file it already had in context. You pay for it twice and it takes up room twice over.
• Whole dependencies for one function: pulling in a large file to reference a small part of it.
• Standing config: CLAUDE.md, skills, and MCP definitions occupy window space on every turn from the start, before the task begins.
• One session, many tasks: dragging a finished task's context into an unrelated new one.

How to compact less

• Start a new session when the task changes. If you change one habit, change this one. A new task rarely needs the old task's history, and carrying it is pure cost.
• Keep the handoff scoped: hand over the files the task touches, not the directory they live in.
• Notice your own knee: most people have a context size past which their sessions reliably start degrading, with more re-reads and more tool errors. It is personal rather than universal, and it is measurable from your own history.
• Prune your standing config: anything in CLAUDE.md or an always-on skill is charged on every turn of every session forever. Most of these files have material in them that has never earned its place.

Finding out how often it happens to you

You do not have to guess. Claude Code already writes a transcript of every session to your machine, and those transcripts record where the window went and when it compacted.

npx @promptster/cc-audit

It reads what is already in ~/.claude/projects, prints to your terminal, and sends nothing. It reports how much you spent carrying context, how often the agent re-read something it already had, and the context size where your sessions start to degrade. It never reads the contents of your files.

What compaction is NOT

• Not a bug: it is the agent doing the right thing with a full window.
• Not the same as the model getting worse: it lost context, not capability.
• Not something to solve by buying a bigger window: a larger window postpones compaction. It does not make carrying irrelevant tokens any cheaper.
• Not free: it costs tokens to do, a cache rebuild to recover from, and detail to live with.

Related reading

• Rate-limit window — the allowance all of this is spent against.
• Context efficiency — the discipline that keeps you away from the ceiling.
• Model right-sizing — the other habit that quietly moves your spend.