Claude Code Idle Compaction: What It Does and How to Turn It Off

If Claude Code printed "Compacted while idle" after you came back from lunch, that is idle compaction, and you can turn it off with "idleCompaction": false in settings.json. It is a cost feature that quietly trades detail for a cheaper first message, and whether it helps you depends on how big your session is and how you pay.

The behavior is now in the official release notes. Claude Code 2.1.299 (October 14, 2026) says a conversation over 200K tokens that sits idle for about 54 minutes is compacted before its prompt cache expires. Version 2.1.299 also added CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS to change the 200K minimum. The feature itself is older than the note: a GitHub bug report places it in 2.1.286 as a silent default, which is why some people hit it weeks ago and wondered what happened to their context.

What the release notes say#

From the Claude Code release feed, the relevant lines are:

• 2.1.299: idle compaction in the terminal, with the 54-minute and 200K figures above.
• 2.1.299: CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS changes the 200K minimum, and "idleCompaction": false in settings.json turns the feature off.
• 2.1.302 (October 16): an "Idle compaction" row in /config, so you can flip it without editing JSON.

To turn it off in settings:

{ "idleCompaction": false }

Or open /config on 2.1.302 or later and toggle the Idle compaction row. If you want it on but only for very large sessions, raise the minimum with the environment variable instead.

Why 54 minutes: the cache math#

The number comes from Anthropic's prompt cache. Per the prompt caching docs, the default cache lifetime is 5 minutes and a 1-hour option exists. Cache reads cost 0.1x the base input price (0.05x for Opus 5.5 and Sonnet 5.5, 0.025x for Fable 5.1), a 5-minute write costs 1.25x and a 1-hour write costs 2x.

So a long session that goes cold has to re-write its entire context at write prices on your next message. Compacting while the cache is still warm means the expensive re-write covers a much smaller summary. A GitHub feature request, issue 66115, laid out the arithmetic with one user's numbers. They measured compacted context at roughly 20 percent of the original across 142 compactions, and described a roughly 740K-token coordinator session on an API key that cost about $9.25 per wake from a cold cache against about $0.19 to compact while warm. Treat those as one user's measurements, not a benchmark.

The same thread supplies the part the release note leaves out. Per a commenter's binary analysis reported in issue 98747, the timer only arms when the cache lifetime is one hour and fires at about 90 percent of the way to expiry, which is where 54 minutes comes from. A repo collaborator in that thread said a setting was coming, and a commenter's binary analysis supplied the 200K default with a 100K floor. I did not verify the cache lifetime behavior for each plan type myself, so check the bill and the "Compacted while idle" message before assuming either way.

The angle: who should leave it on#

My read of the trade, from the sources above rather than a test of my own:

• Leave it on for huge single-purpose sessions you walk away from for an hour or more, especially on pay-as-you-go keys. The saving is real when the alternative is a multi-hundred-thousand-token cold re-write, and the summary is usually enough to continue.
• Turn it off for sessions that hold fragile state: exact instructions, a plan you are midway through, or an orchestrator that expects files to still be in context. The bug report describes a summary replacing "exact instructions, decision rationale, and in-flight state" with no warning.
• Raise the minimum if you run 1M-context sessions. One commenter running 1M-context sessions reported frequent idle compactions, which follows from a 200K default.
• Move the important parts out of the conversation. Anything that must survive a compaction belongs in CLAUDE.md or an imported file, which is also the best practice for any context engineering setup.

If you do not know whether you are on a one-hour cache, the feature may rarely fire for you. Check what your sessions actually cost before optimizing, and see our cache observability guide for how to measure cache hit rates, and the prompt caching production guide for the API side.

What people are actually saying#

• Mostly annoyed by the rollout, not the idea. In issue 98747, many commenters objected to a default-on change with no opt-in and no documentation. The reporter confirmed that idleCompaction: false fixed it and closed the issue on October 6.
• The sharpest disagreement is about detail loss. One commenter running an orchestrator workflow said automatic compaction broke the process because files were not re-read afterward. Others asked for a separate toggle so threshold compaction can stay on while idle compaction is off.
• The defenders have a cost case. In issue 66115, some argued the feature saves real money on large sessions. The counter-case is also there: Max-plan users described a cold 500K-token read as negligible, and one analysis noted that compacting after the cache has already expired can cost more than doing nothing.
• Open requests. A distinct trigger value so hooks can tell idle compaction from threshold compaction, and proper docs for the setting.

What to do Monday#

1. Update to 2.1.302 or later and open /config to see the Idle compaction row.
2. Decide per project: off for stateful agent work, on for big research or refactor sessions you leave running.
3. Put standing instructions in CLAUDE.md so a summary can never lose them. See hooks if you want to snapshot state around compaction, and the usage limits playbook for the quota side.

Continue Reading#

• Claude Code Token Burn Is an Observability Problem - measuring cache hits and spend
• Prompt Caching for Claude API in Production - the API-side cache rules
• Context Engineering Guide - what belongs in the conversation and what does not
• Claude Code Usage Limits Playbook - staying inside the quota

Sources#

• Claude Code release feed (2.1.299, 2.1.302) - Anthropic, GitHub
• Prompt caching docs - Anthropic
• Issue 98747: idle compaction discards working context - GitHub
• Issue 66115: auto-compact on idle timeout - GitHub