Claude Code idle compaction: a cheap summary now or a full cache rewrite later

Claude Code 2.1.299, released October 14, added a feature you never call. Leave a big conversation alone in the terminal for about 54 minutes and Claude Code compacts it on its own, a few minutes before the one-hour prompt cache would expire. Per the settings reference, when you come back the conversation shows this notice:

Compacted while idle, before the prompt cache expired

The release note sells it as saving you a reprocess. That is true, and it is also a decision made on your behalf, with a cost you can measure and a loss you cannot. The odd part is who gets it. By default the feature runs for subscribers inside their plan’s usage, who pay in quota at an exchange rate Anthropic does not publish. The people who would see the saving in dollars, on API keys, are left out unless they pay double for every cache write. And whatever it saves, the summary that replaces your history now gets written while nobody is watching.

The idle behavior itself is documented, not observed; the one thing I ran is the TTL check below, on 2.1.300.

What does Claude Code idle compaction actually do?

It runs the normal compaction step early, while the cache is still warm. Compaction sends your whole conversation plus a summarization instruction as one request. At minute 54 that prefix is still cached, so the request reads it at the cache-read rate. At minute 61 it would not be, and whatever you send next reprocesses the full history.

The prompt caching page says it directly: after a break longer than the cache lifetime, the summarization request “reprocesses the full history as uncached input.” Idle compaction moves that summarization to the last cheap moment.

When does Claude Code idle compaction fire?

Only when five conditions in the settings reference hold at once. The session is an interactive terminal session, so a claude -p run or an Agent SDK session never gets it. The conversation is on the one-hour prompt cache TTL, which is the condition that filters most people out. Claude Code can fetch feature flags from Anthropic, which DISABLE_GROWTHBOOK=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns off, taking idle compaction with it. The context has reached the threshold, 200,000 tokens by default. And about 54 minutes have passed since the last request, with the machine awake at that point: a laptop that sleeps through minute 54 does not compact.

My own agents run as interactive Claude Code sessions in tmux on a Max subscription, so the first condition holds for them, and the second does as long as they stay inside the plan’s usage. That is the profile the conditions select for. A team running headless jobs on API keys gets none of it.

Which Claude Code sessions are on the one-hour cache TTL?

By default, only the main conversation on a Claude subscription within its plan’s included usage. The prompt caching page lays out the buckets: on a subscription the main conversation gets one hour; with an API key, usage credits or a cloud provider it gets five minutes. Subagents, workflows and compaction itself get five minutes in both cases, apart from a few helper requests Anthropic sets to one hour server-side. Once a subscription runs past its plan limit and draws on usage credits, Claude Code drops the main conversation to five minutes by default, and idle compaction stops applying unless you have pinned the TTL yourself.

You can check which TTL a request uses without waiting an hour. The docs suggest a one-shot run:

claude -p "Reply with the single word: ok" --output-format json

On 2.1.300 with a subscription, the usage block came back with every cache write on the one-hour lifetime:

"cache_creation": {
  "ephemeral_1h_input_tokens": 34503,
  "ephemeral_5m_input_tokens": 0
}

A -p run is in the same main-conversation bucket as your interactive turns, so it tells you which default applies to your billing. If the writes land in ephemeral_5m_input_tokens, your interactive sessions will not qualify either until you change the TTL. To opt in on an API key, set the main conversation to one hour:

{
  "promptCacheTtl": "1h"
}

That is not free. One-hour cache writes bill at 2 times the base input price against 1.25 times for five-minute writes, and the docs warn the longer TTL loses money on short bursts of work that never sit idle past five minutes.

Does the Claude Code 200K threshold fit your context window?

Only on a 1M-token window; on a 200K window the default almost never triggers. Auto-compaction on a 200K window runs before the conversation reaches 200,000 tokens, so a conversation there rarely gets big enough to qualify, and the settings reference suggests lowering the threshold to 150,000 for those sessions. Models with a native 1M window, which include Opus 5.5, Sonnet 5 and later, Haiku 5.5 and the Fable models, auto-compact only at about 967K, so the 200K default bites there. My TTL check reported contextWindow: 1000000 for Opus 5.5.

Set the threshold in the env block of a settings file. Values below 100,000 are raised to 100,000, the floor:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

The release note says the variable and the setting need 2.1.290 or later, while the feature itself shipped in 2.1.299, and it does not explain the gap. Run claude --version and plan on 2.1.299 as the real minimum.

What does Claude Code idle compaction cost compared with coming back cold?

On the old prefix alone, the warm summary is roughly 40 times cheaper than a cold rewrite, but that is not the whole bill. Take a 200K-token conversation on Opus 5.5 and count in base-input-price units, using Anthropic’s published multipliers:

The 10K is only the read. Idle compaction also pays for the summary’s output tokens, and the next turn rebuilds a shorter context: the summary plus the instructions, memory, files and skills Claude Code restores after any compaction. Some of that hits the existing system-prompt cache; the rest is written fresh. So the real saving is smaller than 40 times, and how much smaller depends on how much gets restored.

Two more caveats. On a subscription within plan usage none of this is billed in dollars; it is quota, and Anthropic does not publish how quota weighs cache reads against writes. And the cheap path pays off only if you come back. A session a timer kills at the hour, or one you abandon, pays for a summary nobody reads.

What does a Claude Code compaction summary lose?

The verbatim conversation, from the model’s working context. The session record on disk stays; what changes is what Claude sees on the next turn. Per the context-window docs, the summary keeps your requests and intent, key technical concepts, files examined or modified with important snippets, errors and their fixes, pending tasks and current work. Full tool outputs and intermediate reasoning drop out of context.

The base instructions and output style still apply after compaction. Claude Code reloads the project-root CLAUDE.md, unscoped rules and auto memory from disk, re-reads up to five recently modified files it touched (a file over 5,000 tokens comes back only as a path), re-injects the bodies of skills you invoked (capped at 5,000 tokens each and 25,000 in total, oldest dropped first), and adds the output of SessionStart hooks that match the compact source. Rules with paths: frontmatter and nested CLAUDE.md files are summarized away with the history and reload only when Claude touches a matching file again.

So anything that must survive a compaction, idle or not, goes in an unscoped rule, the project-root CLAUDE.md or a SessionStart hook on compact. A decision you only stated in chat is exactly what a summary paraphrases. I have argued before that the summary coming back is an input to treat with care, not a save file, and with idle compaction you are not even there when it gets written.

The docs leave one case open. Idle is measured from the last request, and background commands keep running across a compaction, but nothing says whether a running background command or a pending scheduled wakeup holds off the idle timer. If you park sessions on long builds, that is worth a test before you rely on it either way.

How do you turn off Claude Code idle compaction?

"idleCompaction": false in any settings file turns off only idle compaction (2.1.290 or later; on older versions turn off autoCompactEnabled instead). DISABLE_AUTO_COMPACT=1 turns off idle compaction and normal auto-compaction together, leaving only a manual /compact. Because idleCompaction takes any settings file, you can switch it off for one project in .claude/settings.local.json and leave it on everywhere else:

{
  "idleCompaction": false
}

My read, not measured: keep it on where the work is the files, such as coding and maintenance, because the summary plus the re-read files carry most of what matters. Turn it off, or raise the threshold, where the value is the thread itself, such as a long argument or a design discussion you mean to pick up mid-sentence. There, the input saving is cheap next to a paraphrased decision.

How do you measure Claude Code idle compaction with OpenTelemetry?

Turn on the OpenTelemetry exporter and read the claude_code.api_request events. The quickest local setup prints them to the console:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=console
export OTEL_METRICS_EXPORTER=console

You need three attributes. query_source names the subsystem that sent the request, and compact marks compaction calls, idle or otherwise, so pair it with the time since your previous request and the notice in the transcript. cache_read_tokens on that call shows whether it read warm. And 2.1.300 added cache_creation_5m_tokens and cache_creation_1h_tokens, splitting cache writes by lifetime; the split is in the 2.1.300 release notes, while the monitoring reference lists only the combined cache_creation_tokens. A warm idle compaction looks like a compact request with a large cache read, followed by a turn that writes the much smaller compacted context. A large one-hour write on your first message back fits a missed window, but a model switch or a changed prefix produces the same signature, so check those before blaming the clock.

Without OpenTelemetry, /usage shows a Prompt cache (main) line with the session’s hit ratio, miss count and whether the cache is warm right now (2.1.251 or later), and names the likely cause of the last miss on 2.1.260 or later. On the API side, cache diagnostics tells a changed prompt apart from an unchanged one whose cache entry was simply gone.

What should you check first about Claude Code idle compaction?

Run the one-shot TTL check. If your writes are five-minute, the feature does nothing for you, and the only question is whether one-hour writes are worth paying for. If they are one-hour, look at your context window: on 200K, lower the threshold or accept that it rarely fires. Then decide per project whether you would miss the thread or the files. A summary written at minute 54 is cheap, and it is also the one piece of context nobody reviewed before the session went on.