Tahir Nazir

Posted on Oct 15 Originally published at its-tahir.com

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

#claudecode #troubleshooting #costoptimization #aiagents

Originally published at its-tahir.com.

To stop Claude Code's "Compacted while idle" summaries, add "idleCompaction": false to your settings (version 2.1.290 or later). It's a cost-saving feature, not a bug, and the details below include 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.

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. Anthropic switched the feature 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.

Why Claude Code says "compacted while idle"

It's about the prompt cache. This section covers only the part idle compaction depends on; for how caching, context size and idle sessions add up to your overall usage, see why Claude Code uses so many tokens.

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:

Condition	Detail
Anthropic has it switched on	A server-side flag sets it to off, log-only, or compact
Auto-compact is on	Turning off `autoCompactEnabled` also stops idle compaction
You haven't opted out	The new `idleCompaction` setting isn't `false`
The cache lasts one hour	It skips sessions on the five-minute cache
The context is 200,000 tokens or more	The default threshold — never lower than 100,000
You've been away long enough	It fires 90% of the way to the cache expiring, so about 54 minutes
Nothing else is happening	No turn running, no newer request, not near your rate limit, and the cache still warm

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. (If auto-compaction keeps firing and the context refills straight away, that's a different problem — what "Autocompact is thrashing" means.)

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

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

Key takeaways

'Compacted while idle, before the prompt cache expired' is a cost-saving feature: Claude Code summarises a long session just before its one-hour cache expires, so your next message doesn't reprocess the whole history.
In the 2.1.290 code it needs a one-hour cache, at least 200,000 tokens of context and about 54 minutes of inactivity — and Anthropic's server-side switch decides whether it runs at all.
"idleCompaction": false in settings.json (2.1.290+) turns it off while keeping normal auto-compaction at the context limit.
The code is already in 2.1.285, so downgrading isn't a reliable fix; CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS can raise the threshold instead (undocumented, minimum 100,000).
The full transcript survives on disk under ~/.claude/projects/, and anything in CLAUDE.md reloads after every compaction.

For other Claude Code errors, from SSL failures to 529s, the full list of Claude Code errors and fixes groups them by cause.

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.

FAQ

Why does Claude Code say 'Compacted while idle, before the prompt cache expired'?

Claude Code summarised a long conversation shortly before its one-hour prompt cache was due to expire, so your next message doesn't have to re-send the whole uncompacted context at full price. In the 2.1.290 code it only does this for sessions on a one-hour cache with at least 200,000 tokens of context, roughly 54 minutes after the last activity, and only when Anthropic has the feature switched on server-side.

How do I turn off idle compaction in Claude Code?

Add "idleCompaction": false to a settings.json file — your user settings at ~/.claude/settings.json, or a project, local or managed settings file. It needs Claude Code 2.1.290 or later, and it leaves normal auto-compaction near the context limit switched on. Setting it to true does not force idle compaction on.

Can I get my context back after an idle compaction?

Not inside the session — the summary replaces the verbatim conversation. The full transcript is still saved on disk under ~/.claude/projects/, so you can re-read the exact instructions from there. To protect standing instructions in future, keep them in CLAUDE.md, which reloads automatically after every compaction.

Does downgrading Claude Code stop idle compaction?

Not reliably. The idle-compaction code and its server-side switch are already present in 2.1.285, before most people noticed the behaviour. Whether it runs is controlled from Anthropic's side, so the dependable way out is the idleCompaction setting in 2.1.290 or later.

Sources