Claude Code Idle Compaction Explained

If you leave a long Claude Code terminal session idle and come back an hour later, the expensive part is often the first message after the break. Prompt caching had kept your history cheap to re-read. Once that cache expires, the next turn can reprocess the whole conversation as uncached input.

Anthropic shipped idle compaction for the terminal to close that gap. A large conversation left idle is compacted shortly before the one-hour prompt cache expires, so your next message does not pay the cold-reprocess cost.

This guide sticks to the official changelog, prompt caching docs, costs docs, and settings reference.

What idle compaction does

From the Claude Code changelog:

a 200K+ token conversation left idle for about 54 minutes is compacted before its one-hour prompt cache expires, so your next message doesn’t reprocess it all

In practice that means:

1. You are in a terminal session (not a general Desktop-only feature description).
2. The conversation is large enough (about 200K tokens by default).
3. You leave it idle long enough that the one-hour cache is about to die (~54 minutes).
4. Claude Code runs a compaction while the cache is still warm.
5. When you return, the next turn works against a shorter summarized history instead of a full uncached reprocess of the old transcript.

The prompt caching docs put the same idea in one sentence: if you leave a long conversation idle in a terminal session while it is on the one-hour TTL, Claude Code can compact it shortly before the cache expires.

Why the cache TTL matters

Claude Code re-sends full context on every turn. Prompt caching reuses the unchanged prefix so only new content is fully processed. Cache entries expire after inactivity. Each hit resets the timer.

On a Pro or Max subscription, within plan usage, the main conversation typically gets a one-hour TTL. On usage credits, an API key, or a cloud provider, the default for the main conversation is often five minutes unless you set a longer TTL yourself. See Cache lifetime and the costs page note that subscription TTL is often one hour.

Idle compaction is aimed at the one-hour case: a long terminal session that sits quiet past the point where the next message would miss the cache.

The costs docs spell out the failure mode idle compaction avoids:

your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context

That is the bill you feel after lunch if you leave a 200K+ session open and send “still there?” an hour later.

Compaction vs a cold resume

Compaction replaces message history with a summary. By design it invalidates the conversation-layer cache prefix, because the next request has a new, shorter history.

How expensive that summarization request is depends on whether the old prefix is still cached:

The docs are blunt: /compact costs the most when you resume an old session. Mid-session /compact while the cache is warm is comparatively cheap. Idle compaction schedules that warm path for you, a few minutes before the TTL would make summarization expensive.

After either path, the following turn rebuilds cache for the shorter summary. That rebuild is usually not the slow part. The expensive part was reprocessing the full pre-compact history with no cache.

For more on how compaction fits into context management, see Deep Dive: Skills & Context.

Requirements and defaults

Confirm your install with claude --version. The changelog lists idle compaction and the settings together around the 2.1.286–2.1.290 window; the env var and idleCompaction key both need v2.1.290 or later.

How to configure it

Turn it off

From the settings reference and changelog, put this in user, project, local, or managed settings:

{
  "idleCompaction": false
}

Use this if you want full history preserved across long idle periods and are willing to accept a cold reprocess (or you prefer to run /compact yourself).

Raise or lower the token floor

From the environment variables docs:

• Variable: CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS
• Default: 200000
• Values below 100000 are raised to 100000
• Non-positive or non-integer values are ignored

Shell example:

export CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=100000
claude

Or under env in settings.json so every session gets it:

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

Lower the floor if you want idle compaction on mid-size sessions. Raise it if only the heaviest transcripts should auto-compact while idle.

Related compaction controls

Idle compaction is one lever. Others still matter day to day:

• autoCompactEnabled / autoCompactWindow: when Claude Code auto-compacts as context fills during active work (settings reference).
• /compact: manual compact at a natural break between tasks.
• /clear: start fresh when switching to unrelated work (no summarization cost).
• promptCacheTtl: choose 5m or 1h for the main conversation cache lifetime (v2.1.242+).

The costs docs recommend clearing between unrelated tasks and compacting with focus instructions when you need continuity.

A practical workflow for long sessions

Solo indie work often looks like this: you open one terminal session for an app area, dig into logs and files for an hour, step away, then come back to finish. For something like Molip, that might be a morning on Screen Time blocking and an afternoon on charts.

A simple pattern that matches the docs:

1. Keep one long session per area, not one mega-session for the whole monorepo. Parallel Desktop sessions with worktrees are covered in Claude Code Desktop Parallel Sessions.
2. Compact yourself at phase boundaries (/compact Focus on open bugs and file paths) while the cache is warm, instead of waiting for auto-compact mid-task.
3. Let idle compaction cover the lunch gap on large terminal sessions with a one-hour TTL.
4. Use /clear when the next job is unrelated. Continuity is not free.
5. Watch /usage for cache miss notes after long breaks. The Session block can show whether the cache is warm and how recent misses looked (v2.1.251+ for the prompt-cache line).

Memory and prompts also affect what survives across turns. See Deep Dive: Memory & Prompts if CLAUDE.md edits seem ignored mid-session (they load at start, then after /clear, /compact, or restart).

What idle compaction does not do

A few boundaries worth stating so expectations stay accurate:

• It does not replace good session hygiene. A vague all-day chat still burns tokens while you are active.
• It does not keep every tool output forever. Compaction summarizes; detail lives in files and git.
• It is described for the terminal idle path with a one-hour TTL. Do not assume identical behavior on every surface or every billing mode without checking TTL.
• It does not invent dollar savings numbers for you. Official docs explain the mechanism (warm summarization vs full uncached reprocess). Exact cost depends on model, context size, and plan.

If you are new to Claude Code, start with Getting Started and Vibe Coding with Claude Code, then come back here when sessions start lasting hours.

Checklist

• Claude Code v2.1.290+ if you need idleCompaction or CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS
• Confirm you are on a one-hour main-conversation TTL when you care about the ~54-minute idle path
• Leave idle compaction on unless you have a reason to keep full idle history
• Tune CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS only if the 200K default is wrong for your session size
• Prefer manual /compact between tasks; use /clear for unrelated work
• Check /usage after long breaks if spend looks high

Browse the rest of the app catalog if you want the product side of this workflow. The coding habits above are what keep Claude Code sessions usable while those apps ship.

Sources

• Changelog (idle compaction): code.claude.com/docs/en/changelog
• Prompt caching / compaction: code.claude.com/docs/en/prompt-caching
• Costs and context: code.claude.com/docs/en/costs
• Settings (idleCompaction, auto-compact): code.claude.com/docs/en/settings-reference
• Env vars (CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS): code.claude.com/docs/en/env-vars