Claude Code auto compact: what it costs and what you lose (2026)

Quick answer

I spent 14 September 2026 reading how Claude Code auto compact actually works, after a long session compacted at a point I did not expect and came back having quietly forgotten a rule I rely on.

Three things turned out to be true, and none of them is what the status line suggests.

The trigger is a token boundary, not a percentage. Where it sits depends on your model and your plan, and it moves when you switch models mid-session.

What compaction costs is set by cache warmth, not by context size. The same conversation, compacted at minute three and at hour three, is not the same price. That is the opposite of the intuition, and it is the single most useful thing on this page.

What you lose is not uniform. Your project-root CLAUDE.md comes back from disk. A path-scoped rule does not, and will not, until Claude next reads a file that matches it.

The dollar figures will move. Auto compact is under active change, and there is an open regression about it right now. The mechanics below are the part that stays true.

The moment

Thursday, a long refactor, somewhere past the two hour mark. The session compacted on its own, which is what it is supposed to do. Then Claude did something the project rules explicitly forbid, in a directory that has a rule file saying so.

My first assumption was that the rule had never loaded. It had. It loaded when Claude first read a file in that directory, three hours earlier, and compaction summarised it away with the rest of the conversation.

Everything below is read from Anthropic's auto-compact window reference, its prompt caching reference and its what survives compaction table, all read on 14 September 2026. I have flagged what I checked on a running install and what I am repeating from the documentation.

Finding 1: the percentage is a fraction of a number that moves

The indicator says "context left until auto-compact". It is a percentage, so it reads like a fixed fraction of a fixed window. It is neither.

The documented boundaries are token counts, and they are per model and per configuration:

So the denominator behind that percentage is roughly 4.8x larger on a native 1M model than on a 200K one. Switch models mid-session with /model and the percentage is now measuring against a different number. It is not wrong, it is just not the invariant people treat it as.

This is also where the most-read third-party explainers drift. Page-one articles on this term describe the trigger as "around 95% of capacity", which is a reasonable mental model and is not how the docs define it. I am not linking those pages, because the point is the drift rather than a takedown of anyone in particular.

Finding 2: cache warmth sets the price, not context size

This is the one I had backwards, and it is backwards in a useful direction.

The naive model is that compacting a large conversation is a large request, because a large conversation has to be read in order to be summarised. That is half right. It has to be read. What it costs to read depends entirely on whether the prompt cache still holds it.

Anthropic's prompt caching reference, verbatim: "While the cache is warm, that request reads your prefix from the cache, so a mid-session /compact costs a fraction of what the context size suggests and spends most of its time generating the summary."

And the other side of it:

The same page, verbatim: "After a break longer than the cache lifetime, there is no cache left to read, so the summarization request reprocesses the full history as uncached input. This is why /compact costs the most when you resume an old session."

To produce a summary, Claude Code sends a separate request carrying the same system prompt, tools and history as your conversation, plus a summarisation instruction as a final user message. That request is an ordinary request. It hits the cache or it does not.

The practical shape of that:

• Compacting in the middle of active work is cheap relative to the context size, because the prefix is warm.
• Compacting the first thing after lunch is the expensive one, on exactly the same conversation.
• The turn after compaction is never the slow part. It rebuilds the cache for a much shorter summary.

Which inverts the usual advice. "Compact before it gets big" is less useful than "compact while it is still warm".

Finding 3: the cache lifetime halves when you cross your plan limit

The lifetime that decides finding 2 is not a constant either, and the way it changes is unhelpfully timed.

Claude Code assigns a TTL per request from two fixed buckets. Your interactive turns are the main conversation. Compaction, subagents, forks and session titles are everything else.

Read the first row again. On a subscription, inside your included usage, your conversation cache survives an hour of idling. The moment you go past your plan's limit and start drawing on usage credits, Claude Code drops the main conversation to the five minute TTL, because you are now being billed for that usage.

So the regime where compaction is expensive switches on at the moment you are already over budget. A twenty minute break that cost you nothing on Tuesday costs you a full uncached reprocess on Thursday, and nothing in the interface announces the change.

You can hold the hour. Set promptCacheTtl to 1h, or the CLAUDE_CODE_PROMPT_CACHE_TTL environment variable. Both take 5m or 1h and both ignore anything else. There is a separate control for the other bucket, subagentPromptCacheTtl or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL. The docs give v2.1.242 or later for both.

Finding 4: three ways to move the window, and the obvious one is the weakest

You can set the auto compact boundary yourself. There are three surfaces, and their precedence is not the order you would guess.

# 1. In-session command, saves to user settings
/autocompact 500k

# 2. CLI flag, this launch only
claude --autocompact 500k

# 3. Environment variable
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=500000

The environment variable wins. It takes precedence over the command, the flag and the setting, and while it is set /autocompact reports the override instead of changing anything. Type a new value into a session that has the variable exported and you get a report, not a change.

The genuinely surprising part is the other two. The /autocompact command is preempted by a higher-priority settings scope such as managed settings: it saves your value, and your session keeps the scope's window. The --autocompact flag is not preempted that way.

So the ranking, from most to least reliable, is environment variable, then flag, then command. The command is the one the docs surface first and the one most people will reach for.

Two smaller edges in the same area:

The value formats differ per surface. The command and the flag accept 200000, a k or M suffix such as 500k or 1M, and a bare number from 100 to 1000 meaning thousands, so 200 means 200,000. The environment variable accepts plain token counts only. export CLAUDE_CODE_AUTO_COMPACT_WINDOW=500k is not a smaller window. It is a malformed value.

The window is capped at the model's context window. Asking for 1M on a 200K model does not get you 1M. Accepted range is 100K to 1M. /autocompact auto returns to the model's tuned window.

Finding 5: what survives is not what you would guess

Compaction replaces your history with a summary. What comes back afterwards depends on how each thing was loaded, and that distinction is the whole finding.

That fourth row is what bit me. Path-scoped rules and nested CLAUDE.md files are not configuration in the way the root file is. They enter the conversation as message history when their trigger file is read, so compaction summarises them away with everything else, and they come back only when a matching file is read again.

The documented fix is blunt and it works: if a rule must persist across compaction, drop the paths: frontmatter or move it into the project-root CLAUDE.md. There is also a hook escape hatch, a SessionStart hook matching the compact source, whose output Claude Code adds to the compacted context.

Two more numbers from that table worth having:

• The file re-read is capped at five, most recently modified first. A file over 5,000 tokens comes back as a path reference rather than its contents, shown as Referenced file instead of Read.
• Skill bodies are capped at 5,000 tokens per skill and 25,000 total, oldest dropped first, and truncation keeps the start of the file. Which is a quiet argument for putting the instructions that matter near the top of a SKILL.md.

Finding 6: three cheaper things than compacting

Compaction is not the only way to get room back, and it is the most expensive of the four.

/rewind truncates the conversation back to an earlier turn. The remaining history is exactly the content the cache was built from, so the next request hits an existing cache entry instead of building a new one. If you have gone down a path you want to abandon, this is strictly cheaper than compacting it.

/recap generates a summary for display in the terminal and appends it as command output rather than replacing your history, so the cached prefix stays intact. It is a reading aid, not a context operation.

/clear costs nothing at all. When you want a fresh start rather than continuity, it is free, and compaction is not.

And one thing that is not a cheaper option but is worth knowing: Claude Code also clears old tool results from context, which is a separate operation from compaction. Compaction summarises. Clearing removes. The /usage prompt cache line counts both as "expected rebuilds" rather than as cache misses, which is why a session can show rebuild activity without you having run /compact.

The one that surprised me most

Editing CLAUDE.md mid-session does nothing. The project-root and user-level files are read once at session start and held in memory. Your edit does not invalidate the cache, and it also does not apply.

It loads on the next /clear, /compact, or restart.

Which means compaction is quietly doing double duty: it is the context operation, and it is also the moment your configuration edits take effect. The docs are explicit that compaction reloads project context from disk, and that this "cache-hits only if CLAUDE.md and memory are unchanged since the session started". So editing the file and then compacting costs you the project-context cache hit as well, on top of the summarisation.

If you have ever edited a rule, watched Claude ignore it, and concluded the rule was wrong, this is the more likely explanation.

The open regression

Worth knowing before you rely on any of this: there is an open issue against Claude Code reporting that auto compact does not fire at 100% context, leaving the session stuck until the user runs /compact by hand.

As of 14 September 2026 it is labelled bug, area:core and duplicate, marked as a regression, and the reporter puts it at roughly the last twelve releases. The duplicate label is the informative part: this is a cluster, not one person's machine.

I have not reproduced it. My sessions compact on their own. But if yours are hitting the wall instead of compacting, that is a known state and not something you have misconfigured.

What I changed

Four things, in the order they were worth doing.

1. Moved the two rules I actually depend on out of paths:-scoped files and into the project-root CLAUDE.md. That was the original bug and it took two minutes.
2. Set promptCacheTtl to 1h, so the expensive compaction regime does not switch on silently when I cross my plan limit.
3. Stopped setting the window through /autocompact and started setting it through the environment variable, having learned the command is the surface most likely to be silently overridden.
4. Started running /compact at task boundaries while the session is warm, rather than after a break. Same operation, materially different price.

I have also stopped reading the percentage as a measure of anything except "roughly how close am I". For the number that matters, /context gives a live breakdown by category, and the Prompt cache (main) line in /usage gives the hit ratio and whether the cache is warm right now, which after finding 2 is the more actionable of the two. Both need v2.1.251 or later. If you want the longer version of how the window fills in the first place, I wrote that up separately in my context window field log.

What I did not verify

This is a documentation reading plus one running install, and the split matters.

What I watched happen: a session auto-compacting, a path-scoped rule not applying afterwards, and /context and /usage reporting as described.

What I am repeating from Anthropic's documentation and did not instrument: the per-model token boundaries, the TTL table, the precedence order between the command, the flag and the environment variable, and the five-file and skill-token caps. I did not run a controlled cost comparison of a warm compact against a cold one, which is the measurement that would turn finding 2 from a documented mechanism into a number. If you have run it, I would like to see it.

Version-gated items carry their versions because the docs give them: promptCacheTtl and subagentPromptCacheTtl at v2.1.242 or later, the Prompt cache (main) line at v2.1.251 or later, the likely-cause text on cache misses at v2.1.260 or later, and compaction inheriting the session's extended thinking configuration at v2.1.198 or later.

If you only take one thing: compaction is a cache event. Time it against your cache, not against your context bar.

P.S. I spent longer working out why that rule vanished than on the refactor it interrupted. Filed under lessons that only cost you once.