TL;DR Leave it on. If your long sessions stay under 200K, lower the threshold with
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS(minimum 100,000). If you'd rather compact yourself with instructions, set"idleCompaction": false.
Update, October 31, 2026: Since v2.1.314 idle compaction also works in the VS Code chat panel and in Claude Desktop's Code tab, and it no longer depends on the feature flags Claude Code fetches from Anthropic: it runs with telemetry off, and on Bedrock, Vertex, Foundry and LLM gateways once the one-hour cache is on.
You head out to lunch with a 300K-token conversation still open. Until now, your first message back rebuilt the cache from the full history at full price, because the one-hour cache had already expired. Since v2.1.299, Claude Code gets there first: after 54 quiet minutes it compacts the conversation on its own while the cache is still warm, and you come back to a summary instead of 300K cold tokens.
What it actually does
When your last request finishes, Claude Code sets a timer at 90% of the cache lifetime: 54 minutes out of an hour. If nobody has typed anything when it fires and the conversation qualifies, it sends the same summary request as /compact. That request reads your history from the cache, at roughly 10% of the input price, and the summary replaces the conversation.
You see it in the thread when you return:
Compacted while idle, before the prompt cache expired · turn off with "idleCompaction": false in settings.json
It's exactly what I recommended doing by hand before a break, except now it happens even when you forget.
In the VS Code chat panel and in Claude Desktop's Code tab, since v2.1.314, the summary is still written while you're away, but it's held to one side: it only replaces the conversation if the cache has already expired when you send your next message. Come back sooner and you carry on with the full conversation and a warm cache. When it does use the summary, the notice is a different one:
Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json
When it fires and when it doesn't
All of these have to hold at once:
| Condition | What breaks it |
|---|---|
| An interactive session in the terminal, the VS Code chat panel or Claude Desktop's Code tab (on your machine or over SSH) | claude -p, the Agent SDK and subagents don't use it |
| A one-hour cache on the main conversation | With an API key, usage credits, a cloud provider or an LLM gateway it's usually five minutes. "promptCacheTtl": "1h" raises it |
| Context above the threshold, 200,000 tokens by default | A 120K session is left alone unless you lower the threshold |
| Your computer awake at minute 54 | If the laptop is asleep, the timer fires late and skips the compaction |
The sleeping laptop is the easy one to miss: you close the lid on your way to lunch and the cache expires anyway, with no summary in between.
Tuning it
1. Lower the threshold if your long sessions fall short
In settings.json, under env:
{
"env": {
"CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "100000"
}
}
Anything below 100,000 is raised to 100,000, the floor.
2. Tell it what to keep
The summary is written by a model that doesn't know what you'll pick up next. It goes through the same path as /compact, so a # Compact instructions section in your CLAUDE.md tells it what to keep even when you're not there:
# Compact instructions
Keep the failing tests and the files we're migrating.
3. Or turn it off
From /config, in the Idle compaction row, or in settings.json:
{
"idleCompaction": false
}
DISABLE_AUTO_COMPACT=1 turns it off too, along with auto-compact.
If it never fires
Until v2.1.314 it shipped behind a flag Claude Code fetched from Anthropic: telemetry turned off or a cloud provider ruled it out, and on my account, on October 18 and already on v2.1.302, it was still off. Since v2.1.314 that flag no longer decides it, so if it never fires, check the cache first. Open /cost and read the end of the Prompt cache (main) line:
warm (1h TTL, last activity 8m 39s ago)
If it says 5m TTL instead of 1h TTL, the conversation lives on the five-minute cache and there's nothing to get ahead of: "promptCacheTtl": "1h" raises it. If it's already an hour, that leaves the token threshold and the sleeping laptop.
Compacting yourself still pays
This is a safety net, not a replacement. If you know you're stepping away, a /compact with instructions before you get up is still better: you choose what to keep for that specific task, and you don't depend on the laptop staying awake. And if you're not coming back to that conversation, idle compaction bills you for a summary you'll never use: that's a job for /clear.
To see why the first turn back used to hurt so much, read how prompt caching works in Claude Code. And if it's the compaction that fires when the window fills up that worries you, see who decides your auto-compact window. And when the conversation you're reopening was already closed, on Pro and Max you get the resume dialog that shows what an old conversation costs your 5-hour limit before it costs you anything.
Official docs: idleCompaction
Requirements: idle compaction shipped in v2.1.299, and the /config row in v2.1.302. In VS Code, in Claude Desktop's Code tab and without Anthropic's feature flags, since v2.1.314.