Idle compaction is a Claude Code feature that shipped in v2.1.299. When a terminal conversation over 200,000 tokens sits idle for about 54 minutes, Claude Code summarizes it shortly before its one-hour prompt cache expires. Your next message then sends that summary instead of the full history, so coming back from a break no longer means reprocessing the whole session. It’s on by default, and "idleCompaction": false in settings.json turns it off.

Why was resuming a long session after a break so expensive?

The model doesn’t remember anything between requests, so every message makes Claude Code re-send the whole context, from the system prompt to the last tool result. Prompt caching keeps that affordable: the API re-reads the unchanged prefix at the cached rate and only fully processes what’s new.

The catch is that the cache expires after a period of inactivity. Step away from a 300K-token session for lunch, and your first message back recomputes the full input uncached. That turn is noticeably slower.

Running /compact at that point doesn’t save you much. The summary comes from a request that contains your full history. While the cache is warm, that request reads the history from cache and costs a fraction of what the context size suggests. Once the cache has expired, it reprocesses everything uncached. The docs are blunt about it: /compact costs the most when you resume an old session.

What does idle compaction actually do?

It runs the compaction at around 54 minutes idle, just before the one-hour TTL runs out, while the cache is still warm. When you come back you’ll see Compacted while idle, before the prompt cache expired, and your next request carries the much shorter summary.

All of these have to be true for it to kick in:

  • you’re in an interactive terminal session
  • the conversation is on the one-hour prompt cache TTL
  • the context has reached the threshold, 200,000 tokens by default
  • about 54 minutes have passed since the last request, and your machine is awake at that point
  • Claude Code can fetch feature flags from Anthropic

Why does it only work with the one-hour cache?

The API offers two cache lifetimes, five minutes and one hour. Anthropic’s API pricing docs put one-hour cache writes at 2x the base input price, compared with 1.25x for five-minute writes.

Out of the box, Claude Code only requests the one-hour TTL on a Claude subscription within your plan’s included usage, and only for the main conversation (plus a few helper requests). With an API key, a cloud provider or usage credits (including once you go past your plan limit), the main conversation gets five minutes, and idle compaction doesn’t fire.

If you work with an API key and often leave sessions open across long breaks, you can opt the main conversation into the hour with the promptCacheTtl key (v2.1.242 or later):

{
  "promptCacheTtl": "1h"
}

For a single session, CLAUDE_CODE_PROMPT_CACHE_TTL=1h does the same.

The Prompt cache (main) line in /usage tells you whether the cache is warm and which TTL is in effect.

How do I tune or turn off idle compaction?

To turn it off, add this key to settings.json. It’s recognized from v2.1.290 on:

{
  "idleCompaction": false
}

To change the threshold, set CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS. Anything below 100,000 gets raised to 100,000. The docs use this example for a 200K context window, where regular auto-compaction fires before a conversation ever reaches 200,000 tokens:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

DISABLE_AUTO_COMPACT=1 turns off regular auto-compaction and idle compaction together. Manual /compact keeps working.

When should I turn it off?

Whatever the summary leaves out is gone from Claude’s context. When I leave a session in the middle of a tricky debugging thread, with an exact stack trace and a few dead ends I’ve already ruled out, I’d rather come back to the full conversation and pay for the reprocessing once. For that kind of project, put "idleCompaction": false in the project’s .claude/settings.json.

It also won’t run on a third-party provider such as Amazon Bedrock, Google Cloud or Microsoft Foundry, or when you’ve set DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, since Claude Code then skips the feature flag fetch it depends on.

When is a manual /compact or /clear the better call?

Idle compaction catches the break you didn’t plan. When you know you’re about to step away, compact yourself while the cache is still warm and say what to keep:

/compact keep the database schema decisions and the list of files changed

If the task is finished, /clear is enough: the next task starts with a clean context and nothing needs summarizing. For old sessions you reopen with --resume, Pro and Max plans already offer to resume from a summary once the session is over 100,000 tokens and has been inactive for about an hour.

Going further

Module 7 of the course, Optimization & pro workflow, covers day-to-day context management, from the /clear habit between tasks to steering /compact with instructions.