Claude Code's Idle Compaction: What It Does and When to Switch It Off

You leave a long Claude Code session running, go to a meeting, and come back to a new line in the terminal that says "Compacted while idle, before the prompt cache expired". Nothing has crashed, but the conversation you built up over the morning is now a summary, and Claude carries on from that summary rather than the full history. This started appearing in early October 2026 without much announcement, so a lot of people, us included, met it as a surprise.

It's a sensible feature for a lot of sessions, and the reason behind it is money, or plan usage if you're on a subscription. It's also exactly the wrong behaviour for some ways of working, and we've turned it off on our own machines.

What idle compaction actually does

Compaction is the thing Claude Code has always done when a conversation gets too big for the context window. It sends the whole history off in a separate request with an instruction to summarise it, then replaces your messages with the summary. Idle compaction uses the same routine, but the trigger is time rather than size.

According to the settings reference, it runs only when all of these are true:

• You're in an interactive terminal session, which rules out claude -p, the VS Code panel and the desktop app.
• The conversation is on the one-hour prompt cache. By default that means a Claude subscription within your plan's included usage. API key and cloud provider users are on the five-minute cache unless they opt into the hour.
• Claude Code can fetch feature flags from Anthropic. If you've turned off telemetry or non-essential traffic, it doesn't run.
• The conversation has reached 200,000 tokens of context, which you can change.
• About 54 minutes have passed since the last request, and your computer is awake at that point.

The docs are candid about what you lose: "Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost."

Some things do survive. Your project CLAUDE.md, auto memory and any plan written in plan mode are re-injected from disk. Up to five of the files Claude read or edited most recently are re-read, though a file over 5,000 tokens comes back as a path reference rather than its contents. Background commands and background subagents keep running, and Claude is reminded which ones are still going so it doesn't start duplicates. Everything else, including context that hooks added earlier and any path-scoped rules, is summarised with the rest.

A quiet rollout

The timeline explains some of the confusion. Users had actually asked for something like this back in June, in a feature request about avoiding the cost of an expired cache. It then arrived without anyone saying so. People first noticed it on version 2.1.286 at the end of September, with nothing in the changelog, because it was switched on by a server-side feature flag. An Anthropic engineer replied on the GitHub issue that a setting was coming and that it only applied to larger contexts. Version 2.1.290 added the idleCompaction key and the token threshold variable, still without a changelog line. The first time the changelog mentioned it was 2.1.299 on 14 October, the same day Lydia Hallie from the Claude Code team announced it on X, adding in a follow-up that "It does mean that Claude continues from a summary instead of your full context though." Version 2.1.302 added a row to /config so you can turn it off without editing JSON.

Two details that surprised us. The key is idleCompaction, not idleCompact, and if you've typed the shorter one into your settings Claude Code ignores it silently. And setting it to true doesn't force it on. The server-side flag decides whether it runs at all, so true only means you haven't blocked it.

Why Anthropic added it

To see why this exists, you need to know how Claude Code talks to the API. The model remembers nothing between requests, so every time you send a message, Claude Code re-sends the entire conversation: system prompt, your project context, every earlier message and tool result, then your new message. On a long session that's hundreds of thousands of tokens on every turn.

Prompt caching is what makes that affordable. The API caches the start of a request, called the prefix, and when the next request starts the same way it reads the prefix from cache rather than processing it again. A cache read is a fraction of the price of fresh input. The catch is that the cache has a lifetime. The default is five minutes, and there's a one-hour option that costs more to write but survives longer breaks. Claude Code uses the one-hour cache for your main conversation when you're on a subscription within plan usage.

So what happens when you go to lunch? If you come back inside the hour, your next message reads the whole history from cache and it's cheap. If you come back after the hour, the cache is gone, and the next request processes all of it at full price and writes it to cache again. Anthropic's own costs page names this as one of the reasons usage climbs in a long session: "your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context."

Idle compaction gets ahead of that. At the 54-minute mark the cache is still warm, so the summarising request is mostly cheap cache reads plus the output tokens of the summary itself.

The arithmetic

Here's a worked example using the published API prices for Claude Opus 5.5 on 22 October 2026, with a conversation at 200,000 tokens of context. Opus 5.5 costs $4 per million input tokens, $8 per million for a one-hour cache write, and $0.20 per million for a cache read.

So the cold return costs about forty times the warm one, and idle compaction brings it down to roughly $0.34 all in. The timing matters more than the compaction itself. One contributor to the original feature request, dthinkr, set it out neatly: compacting while the cache is warm is cheap, but if the cache has already expired then compacting costs the full cold read plus the new summary, which is worse than doing nothing. That is why Anthropic fires it at 54 minutes rather than waiting until you come back.

Two caveats on those numbers. The size of the summary isn't documented, so the 30,000 tokens and the output cost in the third row are our assumption. And if you're on a Claude subscription, you're not billed in dollars at all, the cost comes out of your plan's included usage, so these figures are the API equivalent of what you'd be spending. On Fable 5.1 the same cold return is $4.00, and on Sonnet 5.5 it's $0.80.

Why we turned it off

That saving is real, and if our sessions were single tasks we'd leave it on. They're not.

We run work for several clients at once, and a lot of it runs through long plans that take more than one sitting. The main Claude Code window on Blake's machine isn't usually doing the coding. It's the planning session and team lead, it holds the plan, briefs sub-agents and workflows, reads their results back, and decides what happens next. Its value is in the detail it's holding: which agent was told what, which approaches have already been ruled out, which client's conventions apply to this piece, what the last three results said and why the next step follows from them.

That is exactly the context a summary flattens. The docs say the plan file and CLAUDE.md come back from disk, and they do, but the working state of a lead that's been running for a few hours lives in the conversation itself, and no file on disk holds it. Worse, the idle window is precisely when a lead session is idle on purpose. It's waiting for a workflow to finish, or Blake's in a client meeting, or it's running overnight. The sub-agents carry on through a compaction, the docs are clear on that, but when their results land, the lead that reads them is now working from a summary of its own plan.

We're not the only ones. One of the clearest comments on the original GitHub issue came from a user who runs the same pattern:

"I use an orchestrator session that loads a bunch of work process, project definition, and other context files, and spawns implementation subagents based on that process. After compaction on the lead, I have it resume by re-reading the critical files. Having this compaction happen automatically and NOT re-read the files breaks my workflow. I use /remote-connect to stay in contact with the orchestrator, so it's not uncommon to go more than an hour between messages if I'm in a meeting."

Another report, issue 102666, makes a point we'd not thought about until we read it. Idle doesn't mean abandoned. That user's session, on a 1 million token window, was compacted at 38% and then 67% full, and "Both times the session was idle only because the model had just presented a decision and was waiting for the user's answer." The summary kept the numbers and lost the reasoning, so when they came back and asked why that option, the model had to re-derive it from scratch. A lead session that asks you a question and waits is idle by the timer's definition, even though it's doing exactly what you want.

That matches our experience. For a session like that, the cost of a cold cache return is a few dollars' worth of plan usage. One Max subscriber on the feature request put it bluntly: a cold read of 500k context on Opus 5.5 is "like 4 bucks at API prices. with max 20x it's less than 0.5%, imperceptible." The cost of the lead losing its working memory partway through a multi-client plan is an afternoon of re-briefing, and sometimes a mistake we only spot later. We'd rather pay for the cache.

Should you leave it on?

Most people should, at least to start with. The question is really about what your long sessions are for.

Leave it on if:

• Your long sessions are one task at a time. A big refactor or a long debugging session compacts well, because the summary keeps the requests and the code and you can always re-read a file.
• You step away for more than an hour fairly often, for meetings, lunch or the school run. Each of those is a cold return without it, and on a subscription with tight plan usage the cold return is one of the bigger single hits a session can take.
• You work with a 1 million token context. The default 200,000 threshold means that on a standard 200k window the normal auto-compact fires first and idle compaction never gets a turn, so in practice this is a feature for big-context sessions, and those are the ones where the cold return hurts most.

Turn it off if:

• Your main session is a planner or orchestrator that briefs other agents and holds state between their results, or it's partway through a long review or investigation where the reasoning so far matters more than the files on disk.
• Your sessions sit idle while something else runs, so the 54-minute timer is the normal case rather than the exception.
• You'd rather choose the moment yourself. Running /compact at a natural break, with a note on what to keep, gives a better summary than one taken at an arbitrary minute.
• You're on an API key or a cloud provider and haven't switched to the one-hour cache. It won't run anyway, so there's nothing to decide.

If you're not sure, leave it on and watch for the "Compacted while idle" line. If you see it and the session carries on fine, you've lost nothing. If you find yourself re-explaining things after it, that's your answer. And whatever happens, nothing is deleted. The full transcript stays on disk under ~/.claude/projects, so you can always ask Claude to go and read the detail back out of the log.

You may also not have it, even though it's switched on. At the time of writing there are two open bug reports, one saying interactive sessions have been writing five-minute cache entries instead of one-hour ones since 2.1.301, which would stop idle compaction ever qualifying, and another where it didn't fire on an 850k token session with the Mac kept awake. Anthropic hasn't confirmed either. Run /usage and read the "Prompt cache (main)" line. If it says "1h TTL" you're in the pool, and if it says "5m TTL" the setting is moot until that's fixed.

How to change it

To turn it off, add this to ~/.claude/settings.json so it applies to every project on your machine:

{
  "idleCompaction": false
}

The key needs Claude Code 2.1.290 or later. On 2.1.302 or later you can also run /config and change the Idle compaction row, which writes the same key to your user settings and applies straight away. If the row isn't there, either another settings file is setting the key or feature flags aren't reachable, in which case idle compaction wasn't going to run anyway.

Turning off auto-compact altogether, with "autoCompactEnabled": false or DISABLE_AUTO_COMPACT=1, also turns off idle compaction, but you probably don't want that, because then nothing saves you when the context genuinely fills up.

Changing the threshold instead

If you'd rather keep it on but make it pickier, the threshold is an environment variable rather than a settings key. CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS sets how big a conversation has to be before idle compaction applies to it. The default is 200,000, the lowest it accepts is 100,000, and there's no documented maximum.

Raising it is useful on a 1 million token context. Set it to 500,000, say, and a session that's merely large is left alone while a session that's enormous still gets compacted before its cache expires. You can put it in the env block of your settings file so it applies everywhere:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "500000"
  }
}

Lowering it works the other way. Anthropic's own example sets it to 150,000 so that sessions on a 200k window, which would otherwise auto-compact before reaching the default, qualify for idle compaction too.

If you keep it on, make the summary better

A few things soften the loss when a compaction does happen, idle or otherwise. The simplest is to compact on your own terms before you leave. Anthropic's /usage screen can even suggest it, with a recommendation row that reads "Compact before you step away", and a /compact with a note on what to keep gives you a far better summary than the automatic one. Keep the state that matters in files, because CLAUDE.md, auto memory and plan files come back after a compaction and chat history doesn't. Add a short "Compact instructions" section to your CLAUDE.md saying what a summary should always keep.

What to do this week

Run claude --version and check you're on 2.1.302 or later, then open /config and look at the Idle compaction row so you know where you stand. Then think about your longest session from the past fortnight. If it was a single piece of work you could have summarised in a paragraph, leave the setting alone and let it save you the cold return. If it was holding a plan together while other things ran, set idleCompaction to false and pick your own moments to compact.

Either way, put a line in your team's CLAUDE.md or onboarding notes about which way you've gone and why, because the next person to see "Compacted while idle" on a Monday morning will otherwise spend twenty minutes wondering what happened to their session.

---

References

• idleCompaction, Claude Code settings reference by Anthropic
• How Claude Code uses prompt caching by Anthropic
• Explore the context window: what survives compaction by Anthropic
• Environment variables: CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS by Anthropic
• Track and reduce costs: why usage climbs in a long session by Anthropic
• Prompt caching pricing and model pricing by Anthropic
• Claude Code changelog, versions 2.1.299 and 2.1.302 on GitHub
• Issue #98747: idle compaction silently discards working context on GitHub
• Issue #66115: the original request for compaction before cache expiry on GitHub
• Issue #102666: idle auto-compaction far below the context limit on GitHub
• Issue #103673: interactive CLI uses 5m cache TTL since 2.1.301 and issue #103931: idle compaction doesn't fire on GitHub
• Lydia Hallie's announcement and follow-up on X
• Claude Code idle compaction: how to turn it off by Developers Digest
• Claude Code CLI idleCompaction new setting on r/claudexplorers