Back to rankings

Claude Code: Idle Compaction Shrinks Long Sessions Before the Prompt Cache Expires

Claude CodeView original changelog

Claude Code 2.1.299 adds idle compaction to the terminal. A conversation of 200K or more tokens that sits idle for about 54 minutes is compacted automatically, just before its one-hour prompt cache expires, so the next message does not have to reprocess the whole history. The threshold can be changed with an environment variable and the feature can be switched off in settings.

Key Takeaways

  • Idle compaction runs automatically in the terminal once a conversation of 200K+ tokens has been idle for about 54 minutes.
  • The timing targets the one-hour prompt cache expiry, so compaction lands just before the cache would be lost.
  • The payoff is that the first message after a break no longer reprocesses the full history, saving time and tokens.
  • CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS lets users change the 200K-token minimum to fit their own workflow.
  • Setting "idleCompaction": false in settings.json turns the feature off for users who want the full transcript kept.
  • Both controls require v2.1.290 or later, and the feature applies to the terminal, not every Claude Code surface.

What changed

Claude Code 2.1.299 introduces idle compaction in the terminal. When a conversation holds 200K tokens or more and the user leaves it idle for about 54 minutes, Claude Code now compacts it automatically. The timing is deliberate: the compaction happens shortly before the one-hour prompt cache expires.

Why it matters

Long Claude Code sessions depend on the prompt cache to keep each new message cheap and fast. Once the cache lapses, the next message normally has to reprocess the entire conversation from scratch, which is slow and costs far more tokens on a large context. Anyone who steps away for lunch, a meeting or an overnight break from a big session has run into this. With idle compaction, the history is already summarized by the time the user returns, so the first message back works against a much smaller context instead of reprocessing hundreds of thousands of tokens.

Controls

Two controls accompany the feature. The CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS environment variable changes the 200K-token minimum, so users who want compaction to kick in on smaller conversations (or only on larger ones) can tune it. Setting "idleCompaction": false in settings.json turns the behavior off entirely for people who prefer to keep the full uncompacted transcript. Both settings need Claude Code v2.1.290 or later.

Trade-offs

Compaction replaces detailed history with a summary, so users who rely on exact earlier tool output staying in context may want to raise the threshold or disable the feature. For most long-running sessions, the change removes a hidden cost of walking away from the keyboard.