Claude Code idle compaction: what it does and how to turn it off

Step away from a long Claude Code session for an hour and you may come back to a notice you have never seen before: “Compacted while idle, before the prompt cache expired.” That is idle compaction, a feature Anthropic shipped in October 2026 and has extended in almost every release since. It is on by default, which is why many people meet it before they read about it.

This post covers what idle compaction does, when it runs, how to tune it or turn it off, and what it changes when you run several agents side by side.

What changed, and when

All dates below are the npm release dates of each version; the descriptions come from the Claude Code changelog.

If you use idle compaction, update to 2.1.318 or later for that last fix.

Why Claude Code compacts while you are away

Every message re-sends the whole conversation. Prompt caching is what keeps that cheap: the API reuses the part it has already processed. But the cache expires after a period of inactivity. Come back after it expires and your next message reprocesses the entire history as uncached input, which is slow and expensive for a 200K+ token conversation.

Compaction is cheapest while the cache is still warm, because the summarization request reads your history from the cache. Idle compaction uses that window: shortly before the one-hour cache runs out, Claude Code writes the summary. When you return, your next message starts from the short summary instead of rebuilding the whole conversation. The prompt caching docs explain the trade-off in detail.

When idle compaction runs

According to the settings reference, a conversation qualifies only when all of these are true:

• Session: an interactive terminal session, the VS Code extension’s chat panel, or the desktop app’s Code tab when the session runs on your machine or over SSH.
• Auto-compaction (autoCompactEnabled) is on.
• Prompt cache: the conversation is on the one-hour TTL.
• Size: its context has reached the threshold, 200,000 tokens by default.
• Idle time: about an hour has passed since the last request, and your computer stays awake until then.

The cache condition matters more than it looks. Claude Code requests the one-hour TTL by default only for the main conversation on a Claude subscription, within your plan’s usage. With an API key or a cloud provider the default is five minutes, so idle compaction does not run unless you set promptCacheTtl to 1h. If you go over your plan’s limit and draw on usage credits, the main conversation also drops to five minutes.

How to turn it off

Pick one:

• Settings file: add "idleCompaction": false to ~/.claude/settings.json, or to a project’s settings file to turn it off for that repository only.
• /config: change the Idle compaction row. It is saved to your user settings and applies right away (v2.1.302 or later).
• Environment: DISABLE_AUTO_COMPACT=1 turns off idle compaction along with automatic compaction. Manual /compact keeps working.

{
  "idleCompaction": false
}

If /config does not show the row, another settings source, such as managed settings, a project file or --settings, probably sets the key. Change it there.

How to tune the threshold

CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS sets how large a conversation must be before idle compaction applies. Values below 100,000 are raised to 100,000.

There is a detail here worth knowing. On a model with a 200K context window, auto-compaction runs before the conversation reaches 200,000 tokens, so at the default threshold idle compaction mostly affects 1M-context sessions. To include 200K-window conversations, lower it:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

What you keep after a compaction

A compaction replaces the message history with a summary, but not everything is lost. The project-root CLAUDE.md and auto memory are re-injected from disk, the plan from plan mode comes back, and Claude Code re-reads up to five of the files it read or edited, most recently modified first. Background commands and background subagents keep running. What goes is detail: exact tool output, long reasoning, the back-and-forth that led to a decision. Our guide to the Claude Code context window covers what survives in more depth.

So the rule of thumb is simple. If you were done with a task, idle compaction saves you money and you will hardly notice it. If you stopped in the middle of something delicate and want Claude to remember every step, turn it off for that project or come back within the hour.

What it means when you run several agents

Idle compaction was designed around one person stepping away from one session. With several agents running in parallel, the picture changes:

• Every session is judged on its own. Sessions in different directories build different cache prefixes, so agents in separate git worktrees never share a cache. Each one that crosses the threshold and sits idle for about an hour is compacted independently.
• Waiting agents are idle agents. An agent that finished its turn and is waiting for your review or your answer to a question counts as idle. When you get to the fourth pane after lunch, it may already be working from a summary. That is fine for “looks good, ship it” and less fine for “actually, go back to the approach you rejected earlier.”
• Subagents and teammates are not the target. They fall into the five-minute cache bucket by default. Idle compaction is about your main conversations.
• Headless runs are not covered. -p runs and Agent SDK sessions are outside the session conditions, so overnight pipelines built on them behave as before. For interactive overnight work, see how to run Claude Code overnight.
• The laptop has to stay awake. If the machine sleeps, the hour passes without a compaction and you are back to paying for an uncached re-read.

A practical setup: keep idle compaction on by default, turn it off in the one or two repositories where an agent tends to wait on you mid-task, and try to answer agents that ask questions within the hour.

Where AgentVera fits

We build AgentVera, a desktop app for macOS, Windows and Linux that runs Claude Code, Codex and 16 other coding agents side by side, each in a real terminal with your own install and login. A few parts of it line up with idle compaction:

• Token savings: auto-compact is on by default for every agent at a 150K-token threshold, using each CLI’s own compact command, and each pane shows its live context size. A message to an agent idle for over an hour first compacts a large conversation, which also covers agents that have no idle compaction of their own.
• Notifications: you are told when an agent finishes or needs input, so fewer agents sit waiting past the hour.
• Token budgets and usage limits: a cap per agent, and each Claude and Codex account’s 5-hour and weekly usage in the status bar.

The free plan includes up to 18 agents, MCP, Git, Docker, SSH and code review. For a wider comparison of tools in this space, see the best apps to run Claude Code and Codex in parallel.

Wrapping up

Idle compaction is a small default with a clear purpose: summarize a long conversation while the cache is still warm, so your return does not cost a full uncached re-read. It needs an interactive session, the one-hour cache and a large enough context. You can lower the threshold with CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, or turn it off with "idleCompaction": false or /config. When several agents wait on you at once, decide per project whether a summary is good enough, and answer the ones that need full context first.

Sources: Claude Code changelog, idleCompaction in the settings reference, How Claude Code uses prompt caching and Explore the context window.