You Stepped Away for an Hour. Claude Code Summarized the Session. Here Is How to Choose.

You came back from a meeting and your Claude Code session shows a line that reads Compacted while idle, before the prompt cache expired. Nothing broke. Claude Code judged that summarizing a large conversation while its cache was still warm would cost less than rebuilding that cache from scratch on your next message, so it did the summary for you. This guide explains when that happens and how to tune it or turn it off. We covered the release as news in our Oct 14 brief; this page is the reference version.

• What it does: after about 54 idle minutes on the one hour prompt cache, Claude Code summarizes an interactive conversation of 200,000 tokens or more.
• How to stop it: set idleCompaction to false in a settings file, or raise the threshold with CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS.
• Who sees it: mainly subscription users within plan usage, because API key and credit sessions default to the five minute cache.

What it is

Idle compaction is an automatic summary that runs on a conversation you have walked away from. Your earlier turns are replaced by a compaction summary, the same kind that /compact or auto-compaction produces, and your next message goes out on top of that summary instead of the full history.

The settings reference lists five conditions, and all of them must hold at once:

1. You are in an interactive terminal session, so a headless -p run never idles into it.
2. The conversation is on the one hour prompt cache TTL.
3. Claude Code can fetch feature flags from Anthropic.
4. The context has reached the token threshold, 200,000 by default.
5. About 54 minutes have passed since the last request, and your computer is awake at that point.

The cost logic comes from the prompt caching docs. While the cache is warm, a compaction request reads your long prefix from the cache, so the summary is cheap. After the cache expires, your next message has to send the full history as uncached input. Compacting a few minutes before expiry turns an expensive cold rebuild into a cheap warm summary.

The tradeoff is fidelity. A summary keeps what Claude judges important, so if you will want exact earlier output after a break, such as a long debugging trail, a higher threshold or turning the feature off may serve you better.

On versions, the docs and the changelog say different things, and we report both as written. The settings docs say idleCompaction and CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS need Claude Code v2.1.290 or later. The changelog first announces idle compaction in v2.1.299, which reached npm at 8:23 PM ET on Tuesday 13 Oct 2026. As of 10:17 PM ET on Thursday 15 Oct 2026, npm showed stable at v2.1.292 and latest and next at v2.1.301. Our reading, not a documented rule: because the feature also depends on feature flags, a stable install may behave differently from a latest one, so trust the compaction line in your own transcript over the version number.

How-to

1. Check your version and channel. Run the first two commands in the script below. If you are on a release older than v2.1.290, the settings reference says idleCompaction is ignored and you should turn off autoCompactEnabled instead.
2. Check your cache TTL. The prompt caching docs say Claude Code requests the one hour cache for the main conversation only on a Claude subscription within your plan's included usage. Usage credits, an API key or a cloud provider default to five minutes unless you set promptCacheTtl to 1h. On a five minute cache there is no hour mark to beat, so idle compaction does not apply.
3. Turn it off if you want exact history. Set "idleCompaction": false in a settings file. The docs list it as an any file key, so it works in user, project, local or managed settings. Normal auto-compaction near the context limit keeps working.
4. Or raise the threshold instead. Set CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS to a positive whole number, either in the env block of a settings file or exported in your shell before you start claude. Anything that is not a positive whole number is ignored, and values below 100000 are raised to 100000. The docs' own example lowers it to 150000, because on a 200K context window a conversation usually auto-compacts before it ever reaches the 200,000 default.
5. Confirm after a break. Leave a large session idle past the hour and look for the compaction line when you return.

# We have not run this script end to end on every platform. Read it before you run it.
# It only checks versions and starts one session with a higher idle threshold.
set -e

claude --version
npm view @anthropic-ai/claude-code dist-tags

# Optional installs, left commented. Pick one channel on purpose.
# stable channel, v2.1.292 as of 10:17 PM ET Thu 15 Oct 2026:
# npm install -g @anthropic-ai/claude-code@stable
# pinned release that first announced idle compaction in the changelog:
# npm install -g @anthropic-ai/claude-code@2.1.299

# Keep idle compaction on, but only for conversations of 300,000 tokens or more.
export CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=300000
claude

Gotchas

• One switch turns off two features. Setting DISABLE_AUTO_COMPACT=1 or "autoCompactEnabled": false turns off both auto-compaction near the context limit and idle compaction. The reverse is not true: "idleCompaction": false leaves normal auto-compaction alone. Manual /compact keeps working in every case.
• Hooks do not see a separate value. Compaction hooks report idle compaction with the auto trigger, the same value auto-compaction uses, so a PreCompact or PostCompact script cannot tell the two apart by trigger.
• A sleeping laptop never compacts. Nothing runs while the machine is asleep, so a session that sleeps through the 54 minute mark simply pays the cold rebuild on your next message.
• Headless and SDK runs are out of scope. The docs limit idle compaction to interactive terminal sessions.
• You cannot go below the floor. Thresholds under 100,000 tokens are raised to 100,000.
• Teams may want one rule for everyone. Our suggestion, not a documented recommendation: teams that review long agent transcripts for audit or debugging, or that pin a release, can set idleCompaction to false in project or managed settings so behavior does not depend on who stepped away from their desk. For more Claude Code controls, see Claude Corner.

For most people on a subscription, leaving it on is reasonable, because it only acts on very large conversations that would otherwise pay for a full cache rebuild. That is our judgment, based on the cost logic in the docs.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever AI you use.