Claude Code 'Compacted While Idle'? How to Turn It Off (and When You Shouldn't)

You left a long Claude Code session open over lunch. When you came back, this was waiting:

Compacted while idle, before the prompt cache expired

You never ran /compact. You were nowhere near the context limit. But the exact instructions you'd given, the reasons behind decisions, and the approach you'd agreed on have been replaced by a summary.

You're not imagining it, and it isn't a bug. It's a cost-saving feature that Anthropic switched on from its side around version 2.1.286, with no release note and, until this week, no way to turn it off. The GitHub issue about it describes one user returning to find seven of their twenty open sessions compacted overnight.

The fix: since 2.1.290, add "idleCompaction": false to your settings. Details below, along with the exact conditions that trigger it — which I took from Claude Code's own code, because the official docs don't describe the feature yet.

Why Claude Code says "compacted while idle"

It's about the prompt cache.

Every message you send carries your whole conversation with it. To keep that affordable, the API caches the conversation so it doesn't have to be reprocessed each turn. But the cache expires after a period of inactivity. Anthropic's caching docs explain that after a long enough gap, "the next request recomputes the full input and re-establishes the cache, which is why the first turn back after stepping away can be noticeably" slower.

On a Claude subscription, the main conversation gets a one-hour cache. So if you have a 300,000-token session and walk away for 61 minutes, your first message back pays to reprocess all 300,000 tokens — against your plan's usage limits.

Idle compaction gets ahead of that. Just before the prompt cache expires, the conversation is summarised — that's what "compacted while idle" means. When you come back, you're paying for the short summary, not the full history.

It's a real saving, and people asked for it. A feature request from June wanted exactly this, and the community had already built add-ons to do it, such as claude-idle-compact. The complaint is that it arrived switched on, silently, for everyone.

The exact rules, from the code

There's nothing about this feature in Anthropic's docs or changelog yet, so I downloaded the Claude Code 2.1.290 package and read the code that decides when it runs.

Idle compaction only fires when all of these are true:

Three things in that table answer the questions people ask most.

"Why does it only happen to some of my sessions?" The 200,000-token threshold. Short sessions are never touched. An Anthropic collaborator confirmed in the issue thread that it currently applies "only for larger contexts (200k+)".

"Why don't I see it on my work API key?" The one-hour rule. On an API key or a cloud provider, the main conversation defaults to the five-minute cache, so idle compaction doesn't run unless you've set promptCacheTtl to 1h.

"I'm on 2.1.285 and still got it." The idle-compaction code and its server switch are already in 2.1.285 — I checked that package too. What changed around 2.1.286 was Anthropic switching it on. Downgrading isn't a reliable way out.

How to turn it off

On Claude Code 2.1.290 or later, add this to ~/.claude/settings.json:

{
  "idleCompaction": false
}

It also works in a project's .claude/settings.json, a local settings file, or managed settings — useful if you want it off for one long-running project but not others.

The setting's own built-in description, from the code, is precise: "Set to false to stop Claude Code from compacting a long conversation while the session is idle. Setting it to true does not turn idle compaction on." In other words, false opts you out, but true can't force it on — Anthropic's server switch still decides that.

This leaves normal auto-compaction alone. That's the one that kicks in when you're about to hit the context limit mid-task, and most people want to keep it.

Don't use the older workaround. Before 2.1.290, the only way to stop idle compaction was to turn off auto-compaction entirely — autoCompactEnabled: false or DISABLE_AUTO_COMPACT=1. Both still work, but they also remove the safety net at the context limit. Now that there's a dedicated setting, there's no reason to pay that price.

Or: make it rarer instead

If you like the cost saving but only want it for genuinely huge sessions, there's a second control. It isn't documented anywhere yet, but it's in the 2.1.290 code:

export CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=500000

That raises the threshold from 200,000 to 500,000 tokens, so mid-sized sessions are left alone while the biggest still get compacted. You can't go below 100,000 — the code raises any lower value to that floor.

Treat it as you would any undocumented setting: it's useful today, but it could change or disappear in any release.

When you should leave it on

It's worth saying plainly: for a lot of people, this feature is a good trade.

If you open a session, work on one task, and walk away when it's done, nothing of value is lost. The summary keeps what Anthropic's docs list — "your requests and intent, key technical concepts, files examined or modified with important code snippets, errors and how they were fixed, pending tasks, and current work." And you stop paying to re-send a huge, finished conversation every time you check back in.

It hurts when the conversation itself is the work product: long sessions where you've built up precise instructions, agreed conventions, or an orchestrator that coordinates subagents. That's who's been hit hardest in the issue thread. The summary keeps the gist and drops the exact wording — and for that kind of work, the exact wording is what matters.

A rough rule: if you'd be annoyed to re-explain it, turn idle compaction off. If you'd just start a fresh session anyway, leave it on and let it save you usage.

If it already happened

The verbatim conversation isn't in the session any more, but it isn't gone. Claude Code saves the full transcript to disk under ~/.claude/projects/, one file per session. People in the issue thread rebuilt their context from those files. Open the transcript, find the instructions you'd given, and paste the important ones back in.

Protect standing instructions from now on. Compaction replaces the conversation, but Anthropic's docs list what reloads automatically afterwards: the system prompt, CLAUDE.md, memory and MCP tools, plus a re-read of up to five of the most recently modified files. Anything you'd hate to lose — conventions, project rules, "never touch this folder" — belongs in CLAUDE.md, not only in the chat.

If you use hooks, one change landed alongside the setting. Idle compactions used to reach PreCompact and PostCompact hooks labelled manual, as if you'd typed /compact yourself. According to the Anthropic collaborator in the thread, from 2.1.290 they're labelled auto. A hook still can't tell an idle compaction from one at the context limit, but at least it no longer looks like something you did.

Quick reference

1. Want it off? "idleCompaction": false in settings, Claude Code 2.1.290 or later.
2. Want it rarer? CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS above 200,000 (undocumented, minimum 100,000).
3. On an older version? Update — downgrading won't help, and disabling auto-compact costs you the context-limit safety net.
4. Lost context? The full transcript is under ~/.claude/projects/.
5. Want instructions to survive any compaction? Put them in CLAUDE.md.

If you're wondering where the usage actually goes in a long session, why Claude Code uses so many tokens breaks it down. Building long-running agent workflows that keep their footing across compactions is part of the work I do — see recent projects.