Claude Code idle compaction

The v2.1.299 release on 14 October 2026 records terminal idle compaction. Its notes explicitly say that the setting and threshold variable require v2.1.290 or later. Do not confuse the release-note date with the minimum configuration version.

The current idle-compaction reference requires an interactive terminal session, a one-hour prompt-cache TTL, access to Anthropic feature flags, enough context tokens, and an awake computer at roughly 54 minutes after the last request. The default threshold is 200,000 context tokens. Those conditions explain why two sessions on the same version may behave differently.

Normal auto-compact handles pressure near the context limit; idle compaction prepares a long, inactive conversation before cache expiry. Manual /compact asks for compaction yourself and can include instructions. None of these means that every old message remains verbatim. See context management.

The v2.1.300 release adds CLI OpenTelemetry attributes and fixes. Those changes are separate from Claude Platform API tracing and are not an idle-compaction configuration prerequisite.

First run the read-only version command in the terminal where you use Claude Code:

claude --version

New in v2.1.302: /config now has an Idle compaction row to switch idle compaction off or back on, and idle-compaction notices explain how to disable it. Use that row when you want the interactive control; the file-based examples below remain useful for an explicit scope. This does not make idle compaction independent of broader auto-compact disables. v2.1.302 changelog.

Choose one scope. For a personal project setting, merge the keys into .claude/settings.local.json at the project root. If you create that file yourself, add it to Git's ignore rules. Do not replace an existing permissions or environment block. For a disposable session, save the JSON in a separate local file, such as idle-compaction.example.json, and launch claude --settings ./idle-compaction.example.json. Launching Claude is a real session; only do that when you intend to use it. Settings files and session overrides.

Example A: leave normal auto-compact on; disable idle compaction

{
  "autoCompactEnabled": true,
  "idleCompaction": false
}

This is the targeted setting for a supported version. It does not override an environment-level disable: DISABLE_AUTO_COMPACT=1 disables both automatic modes, and DISABLE_COMPACT=1 also disables manual compaction. Conversely, autoCompactEnabled: false turns idle compaction off too. See the auto-compact setting and environment reference.

Example B: allow idle compaction from 150,000 context tokens

{
  "autoCompactEnabled": true,
  "idleCompaction": true,
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

The variable accepts a positive whole number; invalid values are ignored, and values below 100,000 are raised to that minimum. A default 200K context window can auto-compact before reaching the default 200,000 idle threshold. Lowering this threshold changes eligibility, not the idle delay, cache TTL or availability of feature flags. Threshold rules.

Which file wins?

For a duplicated key, the documented order is managed settings → command-line settings → project local → shared project → user settings. Shared project settings live at .claude/settings.json; personal cross-project settings at ~/.claude/settings.json. Environment variables are not another level in this list: interaction with settings is defined per variable, and a settings env entry usually replaces an inherited shell value. Check both the setting and variable. Precedence.

1. Save a copy of the original setting before editing. Record the executable version, project path and chosen file; do not copy credentials into a report.
2. Start the intended session and use /status to inspect Setting sources and configuration errors. Loading a file does not prove every key in it is supported. /config exposes Idle compaction from v2.1.302. On earlier versions, a missing menu item does not show that the v2.1.290+ JSON setting is unavailable. Check the executable version before interpreting the menu. Configuration checks.
3. Check whether a managed policy, a session override or a disable variable defeats your intended value. A terminal setting does not establish the same feature in Desktop or the IDE.
4. For an already eligible conversation, the documented idle-compaction indicator contains Compacted while idle. Its absence alone is inconclusive: token count, cache TTL, feature flags, sleep and elapsed time can prevent the trigger. Do not generate a huge conversation merely to test the timer. Expected behavior.
5. Roll back by restoring the prior JSON keys or removing only the keys you added, and relaunch. For a one-session file, omit --settings next time. Removing a setting-file environment variable does not unset it inside an already running process; relaunch after removal. Environment lifecycle.

On a pre-2.1.290 client, the idle-specific key is ignored. The documented fallback is to disable autoCompactEnabled, which also sacrifices ordinary automatic compaction; prefer a supported update when your environment permits it. Do not silently use that broader fallback when your goal is to keep normal auto-compact. Version boundary.

Unknown in this guide: your rollout flags, your effective cache TTL, whether your current session will trigger, the exact summary it will retain, and any resulting monetary saving. We have not measured these.

Current PreCompact documentation uses manual for /compact and auto for automatic or idle compaction. A PreCompact hook can block with exit code 2 or decision: block. Blocking proactive compaction skips it; blocking recovery after an API context-limit error makes that request fail. The auto matcher does not identify idle compaction separately.

PostCompact runs after compaction and receives compact_summary. It can record what happened; it cannot undo a summary already created. Both events discard systemMessage and continue. Do not assume a hook can inject instructions through those fields or preserve all state. This guide does not install a hook.

Before a long pause, write a short checkpoint in a project note you already use: goal, accepted constraints, changed files, test results, open decisions and the next command. Save editor buffers, inspect Git status, and preserve uncommitted work separately when necessary. A conversation summary is not a backup of files or unsaved edits.

After resuming, ask the agent to read that checkpoint and compare it with the real working tree before continuing. Keep durable project instructions in the appropriate project instruction file; don't depend on a buried chat message surviving a summary. This is an editorial recovery procedure, not a claim of lossless compaction. For broader design choices, see agent memory systems.