Skip to content
← Back to release · 2.1.299
New features / v2.1.299

Configure idle compaction threshold

CHANGELOG · original

Added CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS to change idle compaction's 200K-token minimum; "idleCompaction": false in settings.json turns it off. Both need v2.1.290 or later
Open official changelog ↗

Documentation

Documentation excerpt

idleCompaction

Idle compaction compacts a long conversation that you've stepped away from. Your next message then sends a summary instead of the whole conversation. Once compacted, the conversation shows a notice:

  • Terminal: a line that starts with Compacted while idle, before the prompt cache expired
  • VS Code chat panel: a notice that includes a summary written while you were away
  • Desktop app: the same notice, inside a row whose label includes Claude Code notice. If you don't see that row or its text, switch to the Verbose view mode.

Idle compaction is on by default for conversations that meet all of these conditions:

  • Session: you're in an interactive terminal session, in the VS Code extension's chat panel, or in the desktop app's Code tab when the session runs on your machine or over SSH
  • Auto-compaction: autoCompactEnabled is on
  • Prompt cache: the conversation is on the one-hour prompt cache TTL
  • Size: the conversation's context has reached the token threshold, which you can change from its default of 200,000
  • Idle time: about an hour has passed since the last request, and your computer stays awake until then

To turn idle compaction off, set this key to false.

  • Scope: Any file
  • Type: Boolean
    • true: Claude Code compacts idle conversations that meet the conditions
    • false: Claude Code doesn't compact while your session is idle
  • Default: true
  • Per-session overrides: DISABLE_AUTO_COMPACT turns idle compaction off along with auto-compaction
{
  "idleCompaction": false
}

To turn idle compaction off or on from inside a terminal session, run /config and change the Idle compaction row. Your choice is saved to your user settings and applies right away. The row requires Claude Code v2.1.302 or later. If you run one of those versions and /config doesn't show the row, check for these causes:

  • Another settings source sets the key: a value in managed settings, the --settings flag, or a project or local settings file overrides your user settings. Change the key in that source instead
  • Feature flags are unavailable on a version before v2.1.314: where Claude Code can't fetch feature flags from Anthropic, idle compaction doesn't run, so there is nothing to turn off

The key requires Claude Code v2.1.290 or later. On an earlier version, which ignores this key, turn off autoCompactEnabled to stop idle compaction.

Change the idle compaction threshold

Set CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS to the number of tokens a conversation's context must reach before idle compaction applies to it. Use a positive whole number. Values below 100000 are raised to 100000, the lowest threshold.

At the default, a conversation on a 200K context window auto-compacts before it reaches 200,000 tokens. This example lowers the threshold to 150,000 so that those conversations qualify:

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

Idle compaction in VS Code and the desktop app

A notice like this one means Claude Code replaced your earlier conversation with a summary that Claude now works from:

Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json

You don't need to do anything. To turn idle compaction off, set idleCompaction to false in ~/.claude/settings.json on the machine or WSL distribution where the session runs, or in another settings file.

Documentation snapshot · 2026-11-20

Change details