Leave a long Claude Code session alone over lunch and it may not come back the way you left it. Instead of your conversation, there's a summary of your conversation, with one line on top: Compacted while idle, before the prompt cache expired.
That's a feature, not a crash. Anthropic shipped it as idle compaction, and it became a documented, configurable default in v2.1.299 (released October 14, 2026). Here's what it does, how to turn it off or tune it, and what survives when it fires.
Disclosure: Wallaby Token sells API access to Kimi K3, and one section below covers what idle compaction looks like when Claude Code runs on your own key through a third-party endpoint like ours. Everything about the setting itself is from Anthropic's release notes and settings reference, fetched October 16, 2026.
What actually happened to your session
The mechanics, per the v2.1.299 release notes: if a terminal conversation reaches 200,000 tokens or more and then sits idle for about 54 minutes, Claude Code compacts it, summarizing the history, just before the session's one-hour prompt cache expires.
The timing is the whole point. Prompt caching makes resuming a big session cheap, but the cache only lives an hour. Once it expires, your next message would reprocess the entire conversation at full input price. Compacting at the 54-minute mark trades "resume with full context" for "resume from a summary," so the next turn stays small either way. Sessions under 200K tokens are never touched, and short coffee breaks don't come close to the threshold.
Why it can still hurt: a summary is lossy. The exact constraint you dictated forty minutes ago, the naming decision, the "don't touch module X": if they don't survive summarization, Claude quietly works without them. The precise trigger conditions were documented by Tahir Nazir, who read the 2.1.290 package code, including a detail the release notes skip: the feature is gated by a server-side flag on Anthropic's end, which is why some people saw it weeks before it was documented.
The off switch
On v2.1.290 or later, one line in settings.json:
{
"idleCompaction": false
}
That goes in ~/.claude/settings.json, or in a project's .claude/settings.json if you want it off for one long-running repo but not everywhere.
Two caveats worth knowing. First, the setting's own built-in description is careful: false opts you out, but true can't force it on; the server-side flag still decides. Second, on versions older than 2.1.290 the key is ignored entirely; the only workaround there is disabling autoCompactEnabled, which also removes the normal auto-compaction safety net at the context limit. Upgrading is the better move.
Turning it off leaves regular auto-compaction alone. That's the one that fires mid-task when you approach the context window limit, and most people want to keep it.
The threshold knob
If you'd rather keep idle compaction but make it rarer, raise the floor:
{
"env": {
"CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "300000"
}
}
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS takes a positive whole number; anything below 100,000 is raised to 100,000, and the default is 200,000. Same version requirement: v2.1.290 or later.
What survives a compaction
Two things, both worth knowing before you panic:
- The full transcript is on disk. Sessions live under
~/.claude/projects/, so the verbatim pre-compaction history is recoverable, just not reloaded into the live context. - CLAUDE.md reloads after every compaction. Whatever must survive belongs there, not in chat: coding standards, forbidden modules, naming rules. This was good practice before idle compaction; now it's the difference between a summary that's safe to continue from and one that isn't.
The own-key angle: compaction is a billed event
If you run Claude Code on your own API key through a custom endpoint, say a Kimi K3 setup, compaction shows up on your bill as what it is: a large input (the conversation) plus a generated summary (the output). Two consequences follow.
You can see it. On an itemized dashboard, an idle compaction is a recognizable request: big input, moderate output, right around the 54-minute idle mark. When we route Claude Code through our own gateway, every request is itemized per key, so the cost of leaving compaction on versus off is measurable rather than vibes. Whoever your provider is, this is the check to run before and after changing the setting. That visibility is exactly what a flat subscription hides — compaction events never surface as line items there. On a per-request billed key they do, and a trial key with $0.50 of credit is enough to watch one fire.
And the economics cut both ways. On your own key, idle compaction saves money — the summary is cheaper than reprocessing 200K tokens of expired-cache context. Turning it off is a quality decision, not a cost decision: you pay more per resumed session in exchange for Claude remembering exactly what you said. For a session where precision matters, like a migration mid-flight or a multi-file refactor, that trade is often worth it. For a scratch session you'll close anyway, leave the default on.
Quick reference
| Want | Do |
|---|---|
| Idle compaction off | "idleCompaction": false in settings.json (v2.1.290+) |
| It fires less often | CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS above 200000 |
| Instructions to survive | Put them in CLAUDE.md |
| Lost context back | Full transcript under ~/.claude/projects/ |
| On < v2.1.290 | Update; autoCompactEnabled: false works but removes the context-limit safety net |
A note on dates: this guide reflects Claude Code v2.1.299 (October 14, 2026), with sources fetched October 16. Anthropic tunes defaults like this from the server side, so check the current release notes before scripting around the behavior.
Running Claude Code on your own key makes every one of these events visible on a bill you control. A new Wallaby Token account comes with $0.50 in trial credit — enough to run a real session and watch exactly what a compaction costs. The minimum top-up is $20, and the rate stays 10% off the official Kimi K3 list, ongoing.