← Claude Code Hub
Oct 18, 2026 · 5 min read ✦ Tip #232

Claude Code idle compaction: it compacts before your cache expires

You step away from a 300K-token conversation. At minute 54 Claude Code compacts it before the cache expires, so your first message back doesn't pay for the whole history again.

Two one-hour timelines: before, the cache expires at minute 60 and 300K tokens are re-read at full price on return; since v2.1.299, idle compaction compacts at minute 54 reading from cache, and a summary is sent on return

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.

Found this useful? See more of wmedia.es in your Google results.

Add wmedia.es as a preferred source on Google
FREE GUIDE

Approve less, but better.

Ten minutes in, you're hitting yes without reading. That's not review, that's prayer. A 10-page guide with the five levers in order of risk.

  • 1. Rules the first match wins
  • 2. Mode a dial, not a switch
  • 3. Auto mode a classifier approves for you
  • 4. Sandbox a fence the OS puts up
  • 5. Bypass only inside a container
Are you a professional Web developer?

You'll receive the guide by email · You join the Gravitas newsletter · Unsubscribe anytime

of 10
#

Wmedia · 10 pages
FREE GUIDE · 10 pages · 5 levers

Approve less, but better.

Ten minutes in, you're hitting yes without reading. That's not review, that's prayer. A 10-page guide with the five levers in order of risk.

Are you a professional Web developer? · Unsubscribe anytime
How I use AI

My Claude Code workflow.

The skills, agents and instructions I use as a professional Software Engineer. It's called Craft, and it's a plugin you can install.

See the skills

Tired of approving permissions without reading?