Claude Code "Compacted while idle": What Idle Compaction Does and How to Turn It Off#
Published by Alex Sorokoletov
"Compacted while idle, before the prompt cache expired" means Claude Code summarized your conversation while you were away. It does this to a conversation of 200K tokens or more after about 54 minutes idle, just before the one-hour prompt cache expires. To stop it, add "idleCompaction": false to settings.json (v2.1.290 or later).[1]
Why Claude Code compacts an idle session#
A terminal session on the one-hour prompt cache pays the cached input rate while the cache is warm. When the hour runs out, the next message reprocesses the whole conversation at the full input rate. For a 300K-token session, that is 300K uncached tokens to say "continue". Idle compaction replaces the history with a summary shortly before the cache expires, so the next turn starts from the summary.
The cost of that saving is the same as any compaction: detail that is not in the summary is gone. Instructions given early in the session, rejected approaches, and exact file contents are the usual losses. That is the core of the complaint in issue #98747, filed on v2.1.286, when there was no setting to stop it.
How to turn off idle compaction#
Add the setting to ~/.claude/settings.json for every project, or to .claude/settings.json for one project:
{
"idleCompaction": false
}
The setting needs v2.1.290 or later. Setting it to true does not turn idle compaction on. Anthropic turns the feature on remotely, and true only means "do not block it".
To keep idle compaction but apply it only to larger sessions, raise the token minimum:
{
"env": {
"CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "500000"
}
}
Values below 100,000 are raised to 100,000. With the variable unset, the minimum is 200,000.
Turning off auto-compaction also stops idle compaction: DISABLE_AUTO_COMPACT=1, DISABLE_COMPACT=1, or "autoCompactEnabled": false. Before v2.1.290 that was the only way to stop it, at the price of no automatic compaction near the context limit either.
When idle compaction runs#
Every condition in this table must hold. If one fails, the session is left alone.
| Condition | Default | What changes it |
|---|---|---|
| Feature turned on remotely | Off unless Anthropic turns it on | Anthropic's remote configuration |
| Auto-compaction on | On | DISABLE_AUTO_COMPACT, DISABLE_COMPACT, autoCompactEnabled |
| Idle compaction not blocked | Not blocked | "idleCompaction": false |
| Session uses the one-hour prompt cache | Depends on plan and provider | A session on a shorter cache lifetime is never idle-compacted |
| Cache still warm, and the conversation prefix unchanged since the last request | n/a | A lapsed cache or edited history skips it |
| Conversation size | 200,000 tokens | CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS (floor 100,000) |
| Idle time | 90% of the hour, about 54 minutes | Remote configuration, clamped to 50-95% (30 to 57 minutes) |
| No newer request, not near a usage limit | n/a | A request in flight or a usage-limit warning skips it |
If a turn is in flight when the timer fires, the conversation compacts between turns.
A second mode in v2.1.300: compact on return#
v2.1.300 adds a mode that writes the summary in the background while you are idle and applies it when you come back. Its message is "Compacted after an hour idle, using a summary written while you were away". This mode also needs precomputeCompactionEnabled, the setting that lets Claude Code prepare a compaction summary before it is needed. "idleCompaction": false turns off both modes.
Timeline: shipped before it was documented#
| Version | Published | Change |
|---|---|---|
| v2.1.283 | 2026-09-25 | Idle compaction ships, with the "Compacted while idle" message. The only way to stop it is to turn off auto-compaction. |
| v2.1.290 | 2026-10-05 | "idleCompaction": false and CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS arrive. The release notes do not mention either. |
| v2.1.299 | 2026-10-14 | First release-notes entry: "Added idle compaction in the terminal", with both controls marked as needing v2.1.290. |
| v2.1.300 | 2026-10-14 | Compact-on-return mode added. |
For ten days, from v2.1.283 to v2.1.290, idle compaction could run with no setting to stop it except turning off auto-compaction completely.
Should you turn it off?#
Keep it on if your long sessions often sit idle past an hour and you mostly continue the same task, because the next message then costs a summary instead of the full history. Turn it off if you come back to a long session to refer to exact earlier output, if a session carries instructions that a summary tends to drop, or if you prefer to run /compact yourself with custom instructions. A middle option is a higher CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, so only very large sessions are compacted.
FAQ#
Q: What does "Compacted while idle, before the prompt cache expired" mean?
A: Claude Code replaced your conversation history with a summary while the session was idle, about 54 minutes after your last message, because the conversation was over 200K tokens and its one-hour prompt cache was about to expire.
Q: How do I disable idle compaction in Claude Code?
A: Add "idleCompaction": false to ~/.claude/settings.json. It needs v2.1.290 or later. Turning off auto-compaction with DISABLE_AUTO_COMPACT=1 also stops it.
Q: Does "idleCompaction": true turn it on?
A: No. Anthropic turns idle compaction on remotely. true only leaves it unblocked.
Q: What is CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS?
A: The minimum conversation size, in tokens, for idle compaction. The default is 200,000, and values below 100,000 are raised to 100,000.
Q: Which version added idle compaction?
A: v2.1.283, published September 25, 2026. The release notes first mention it in v2.1.299.
Q: Is compactOnIdle a Claude Code setting?
A: No. The setting is idleCompaction, and false is the only value that changes behavior.
Sources: [1] Claude Code changelog, v2.1.299
Related: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE Guide | Context Window Management Guide | CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS in the env-var glossary | Claude Code v2.1.299 analysis