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.
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.
When it fires and when it doesn't
All of these have to hold at once:
| Condition | What breaks it |
|---|---|
| An interactive terminal session | claude -p, the Agent SDK and subagents don't use it |
| A one-hour cache on the main conversation | With an API key or usage credits 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 |
| Claude Code can fetch feature flags from Anthropic | DISABLE_TELEMETRY, DO_NOT_TRACK, Bedrock, Google Cloud, Foundry or the Claude apps gateway rule it out |
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. Setting it to true won't switch it on if it hasn't reached you.
If it never fires
The docs say it's on by default, but it ships behind a flag Claude Code fetches from Anthropic, and the first session after an upgrade may not have it yet. On my account, on October 18 and already on v2.1.302, it was still off. To check yours, the cached value lives in ~/.claude.json (it's an internal name and may change):
jq '.cachedGrowthBookFeatures.tengu_sunny_locket' ~/.claude.json
"mode": "off" means it hasn't reached you yet, whatever your settings.json says.
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.
Official docs: idleCompaction
Requirements: idle compaction shipped in v2.1.299, and the /config row in v2.1.302.