TL;DR I’ve wanted Claude Code to compact my conversations in the background for a long time. It now compacts a long session when I walk away from it for about an hour. My Claude went through my session logs: before idle compaction, I spent around 160 minutes over four months waiting on compactions. Since it arrived on my account on 10 October, I haven’t waited on one.
Motivation Link to heading
My sessions run long. Once a conversation fills the context window, Claude Code stops, summarises everything, and carries on from the summary. In my logs that pause took a median of 111 seconds, with one in ten over two minutes. I kept wishing the summary could happen in the background.
Then this notice started showing up in my sessions:
Compacted while idle, before the prompt cache expired
What idle compaction does Link to heading
On a Claude subscription, the prompt cache for the main conversation lasts an hour. If you come back after it has expired, your next message pays to resend the whole conversation. Idle compaction steps in at about the 54 minute mark: if the session holds more than 200k tokens, Claude Code compacts it while the cache is still warm, so your return starts from a small summary.
The release notes announced it in v2.1.299. My first idle compaction ran on v2.1.294, so Anthropic seems to roll it out per account from their side.
What my logs showed Link to heading
Claude Code writes every session to ~/.claude/projects/ as JSONL, and each compaction leaves a compact_boundary record with its trigger, size and duration. Run this to pull them out:
grep -rh '"compact_boundary"' ~/.claude/projects \
| jq -r '[.timestamp[:10], .compactMetadata.trigger, (.compactMetadata.precomputed // false), .compactMetadata.preTokens, .compactMetadata.durationMs] | @tsv'
To count your idle compactions:
grep -rl "Compacted while idle" ~/.claude/projects | wc -l
Between June and 18 October my logs held:
| Kind | Count | Median wait |
|---|---|---|
| Automatic, while I waited | 72 | 111s |
Manual /compact | 16 | 115s |
| Automatic, summary precomputed | 19 | 0s |
| Idle, while I was away | 44 | none, I wasn’t there |
Three things stood out.
I haven’t waited on a compaction since 10 October. Automatic compaction kicked in for me at around 966k tokens. My sessions hit idle compaction at a median of 317k tokens and dropped to about 20k, so none of them reached the automatic limit. Nine days is a short window, and I can’t prove those sessions would have grown that far, but the 966k figure held across all 72 blocking compactions before it.
Background compaction existed before, on and off. Compaction records carry a precomputed flag. Nineteen of my automatic compactions had it, in two spells: 2 to 6 July and 1 to 9 October. Seventeen of those had no wait. Claude Code has a precomputeCompactionEnabled setting for this, but it only does anything when Anthropic has enabled the feature for your account.
Most idle compactions paid off. I came back to 39 of the first 44 sessions, a median of 5.4 hours later, well after the cache would have expired. I never returned to the other five, so those summaries cost tokens for nothing. Across the returns, I avoided resending about 15 million tokens.
Anthropic’s switch for this flipped within one day. Claude Code caches its feature flags in ~/.claude.json, and I saw idle compaction listed there as off and, an hour later, as compact:
jq '.cachedGrowthBookFeatures | {tengu_sunny_locket, tengu_sepia_moth}' ~/.claude.json
tengu_sunny_locket is idle compaction and tengu_sepia_moth is precompute. My Claude dug these internal names out of the Claude Code binary, so expect them to change.
Opting out and other settings Link to heading
To turn it off, switch off the Idle compaction row in /config (v2.1.302 or later), or add this to ~/.claude/settings.json (v2.1.290 or later):
{ "idleCompaction": false }
The setting only works in one direction. Setting it to true won’t switch idle compaction on if Anthropic hasn’t enabled it for you.
Turning off automatic compaction with "autoCompactEnabled": false or DISABLE_AUTO_COMPACT=1 also stops idle compaction. I’d avoid that route: it removes the safety net when a conversation hits the context limit.
To compact smaller sessions, lower the 200k threshold. Claude Code won’t go below 100k:
export CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=100000
My logs had up to 223 hour-long idle gaps with a session sitting between 100k and 200k tokens, so I’m tempted.
On an API key, Bedrock or Vertex, the main conversation uses a five minute cache by default, and idle compaction never fires. "promptCacheTtl": "1h" (v2.1.243 or later) switches it to the hour-long cache, at the higher write price.
Where I am now Link to heading
Idle compaction gives me part of my wish. It covers the gaps where I walk away, and in my working pattern those gaps have kept sessions small enough to dodge the blocking compaction. A session I hammer for hours without a break should still hit the wall. Precompute would fix that, but it has come and gone on my account.