Claude Code Idle Compaction Saves Cache, but Resumes From a Summary

Claude Code idle compaction can now summarize a large session before its prompt cache expires, even when the context window is not full. The feature targets sessions containing at least 200,000 tokens by default. Its central tradeoff is stark: Claude returns to a cheaper, shorter context, but continues from a generated summary instead of every original turn.

Anthropic engineer Lydia Hallie described the behavior in an October 2026 idle compaction post. Users can disable the feature by adding "idleCompaction": false to a Claude Code settings file. They can also change the minimum context threshold with CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS.

That control arrived after developers reported unexpected compactions in long-running sessions. Their concern was not that compaction existed. Claude Code already summarized conversations near their context limits. The conflict was whether an idle timer should replace a still-usable transcript to reduce the cost of returning after cache expiration.

Claude Code Idle Compaction Changes What Resuming Means

A resumed session can keep its identity while losing the verbatim history that originally established it.

Claude Code stores session messages locally and supports reopening them with --continue or --resume. That persistence can make a session feel like a durable workspace. However, the model only reasons over the context sent into its current request, not every artifact stored on disk.

Anthropic’s context window guide explains that the active context contains conversation history, file contents, command output, project instructions, memories, skills, and system instructions. As those materials accumulate, Claude Code clears older tool output and eventually summarizes the conversation.

Compaction is the act of replacing older conversational material with a shorter summary. The session remains available, and Claude can continue working. Yet the model no longer receives each replaced turn word for word.

The new idle path changes when that replacement can occur. Traditional automatic compaction responds to a shrinking context budget. Idle compaction instead responds to inactivity and prompt-cache timing, provided the session is large enough.

Users began reporting the message, “Compacted while idle, before the prompt cache expired,” after leaving sessions unattended. Reports associated the rollout with Claude Code 2.1.286, although the behavior was controlled partly through a server-side gate. That means installing a particular client version alone did not necessarily reveal the complete rollout state.

The default minimum reported by Hallie and discussed in Anthropic’s public repository is 200,000 tokens. That number is a qualification threshold, not a promise that compaction happens precisely when the conversation reaches 200,000 tokens.

A qualifying session also needs the relevant cache conditions and sufficient idle time. Community investigation in the idle compaction issue found the timer approaching the end of a one-hour prompt-cache period. Users observed the visible event around 54 to 56 minutes after the last activity.

Those timing details came from issue participants examining client behavior and running local tests. Anthropic’s public Claude Code documentation did not initially provide a complete idle-compaction specification. Readers should therefore distinguish three evidence levels: Anthropic’s description of compaction, the engineer’s announcement, and community analysis of implementation details.

The verified product consequence remains clear across those sources. After idle compaction, Claude resumes from compressed conversational state. The original transcript can still exist locally, but its full contents are no longer automatically present in the model’s working context.

That distinction matters because local persistence and model attention solve different problems. A stored transcript supports auditing and recovery. Active context determines what Claude can consider during its next response.

The Feature Trades Context Fidelity for Cache Efficiency

Idle compaction moves work from a potentially cold return to a final warm-cache window, accepting summary loss to reduce repeated context processing.

Prompt caching lets repeated requests reuse matching input prefixes. A cache hit generally requires less input processing than rebuilding the same large prefix after its cache entry expires. Long Claude Code sessions create unusually large reusable prefixes because every turn can include prior messages, tool activity, and project material.

Anthropic’s prompt caching documentation describes cache lifetime and the different treatment of cache writes and reads. A long session that goes cold can require Claude Code to process a substantial prefix again when the user returns.

Idle compaction tries to intervene before that point. While the large prefix remains cached, Claude Code can ask the model to summarize it. A later request starts with the shorter summary and whatever instructions or project material Claude Code restores.

This mechanism favors efficiency when a user intends to resume a large session after a break. Instead of returning with the entire old context, the user returns with a compressed representation that requires fewer tokens to process.

The cost is information fidelity. Summaries preserve selected facts and decisions, but they do not guarantee exact retention of every constraint, discarded option, test observation, or conversational correction.

Anthropic acknowledges the general limitation in its context documentation. It says requests and key code snippets are preserved during compaction, while detailed instructions from earlier conversation can be lost.

That warning becomes more consequential in an agentic coding session. A subtle instruction may govern which migration path is allowed. A rejected hypothesis may prevent Claude from repeating an expensive investigation. A small test anomaly may explain why an apparently obvious fix is unsafe.

These details can look secondary to a summarizer while remaining decisive to the next coding step. A summary can accurately describe the project’s broad objective and still omit the evidence that constrained its implementation.

The risk grows with long, exploratory sessions. A developer might ask Claude to inspect several modules, compare competing designs, run tests, and abandon two approaches. The final direction could depend on negative results scattered across command outputs and brief corrections.

After compaction, Claude may remember that one approach was selected without retaining every reason the alternatives failed. It can then reconstruct a plausible explanation that differs from the actual investigation.

This does not make compaction inherently defective. No finite context-management system can retain unlimited history verbatim. The dispute concerns timing and user intent.

Near a hard context limit, summarization prevents the session from stopping. Before cache expiration, the product is choosing efficiency even though the session might still have substantial remaining context capacity.

That is the primary opponent in this story: cache efficiency versus context fidelity. It is not Claude Code versus another coding assistant. Every long-running agent must eventually manage finite context, but the idle trigger makes Anthropic’s chosen balance unusually visible.

Why Developers Objected to an Automatic Summary

The backlash centered on an unannounced state change, not on the existence of context compression itself.

A developer who manually enters /compact knows that Claude will summarize prior conversation. The command can include a focus, such as preserving API decisions or unresolved test failures. That moment creates a natural review boundary.

Idle compaction removes that immediate choice. A user can leave for lunch, attend a meeting, or wait for external feedback, then return to a session whose active history has changed.

The original GitHub report described multiple working sessions being compacted while idle. The reporter said the summaries omitted exact instructions, decision reasoning, and previously agreed methods. Other users reported seeing the same notification despite not being near their configured context threshold.

These are user reports, not controlled measurements of summary accuracy. They nevertheless identify a credible product risk because Anthropic’s documentation already says early details can be lost during compaction.

The initial implementation also complicated monitoring. According to tests documented in the issue, early idle compactions appeared in hook metadata as manual, despite no user entering /compact.

Claude Code hooks let teams run automation before or after defined events. A misleading trigger label makes it harder to distinguish a deliberate user action from a timer-driven transition.

Claude Code 2.1.290 changed that trigger to auto, according to an Anthropic collaborator in the repository. That separates idle compaction from explicitly invoked /compact, but it does not fully distinguish idle compaction from ordinary threshold-based auto-compaction.

This ambiguity matters for teams that use hooks to preserve working state. A hook might want one policy before an emergency context-limit compaction and another before a cache-driven idle compaction.

The issue discussion requested a distinct idle trigger. As of the reported 2.1.290 behavior, both idle and context-threshold events could appear as auto. The terminal notification identified the idle event for the human, but that notice was not necessarily included in hook input.

The broader product lesson concerns invisible optimization. Developers usually accept an optimization when it changes latency or resource use without changing semantics. Summarization can change semantics because the next model request receives different evidence.

That makes idle compaction closer to an automatic state migration than a background cleanup task. The session identifier remains stable, while the reasoning substrate changes.

Teams running high-stakes migrations, incident response, or extended code reviews have reason to treat that transition cautiously. Their sessions often accumulate constraints that are individually small but collectively important.

Shorter sessions face less exposure because they remain below the minimum threshold. Workflows already built around explicit handoffs also reduce the cost because critical state exists outside the chat transcript.

The pressure therefore falls most heavily on developers who treat one long Claude Code session as a persistent project partner. They gain the most from continuity, but they also lose the most when continuity becomes summary-dependent without an intentional boundary.

The idleCompaction Setting Separates Two Different Safeguards

Users can disable idle compaction without disabling the automatic compaction that protects sessions near their context limit.

Claude Code 2.1.290 introduced a dedicated setting, according to an Anthropic collaborator responding in the public issue. A user later confirmed that the option worked in version 2.1.291.

The basic configuration is:

Claude Code supports settings at several scopes, including user, project, local project, and managed policy levels. Anthropic’s settings reference explains their locations and precedence.

A user-wide preference can go in the personal settings file. A repository team can place project settings under version control when everyone should share the behavior. A local project setting can override behavior without changing the repository’s shared configuration.

The important distinction is between idleCompaction and autoCompactEnabled. The first targets the new timer-based path. The second governs broader automatic compaction behavior.

Turning "idleCompaction": false off preserves normal threshold compaction, based on the behavior described for version 2.1.290. This is useful for developers who want protection near a full context window but reject cache-driven summarization during breaks.

That separation directly answered the strongest user request. Before the dedicated switch appeared, disabling automatic compaction more broadly could also remove the safeguard that prevents a session from reaching its context ceiling.

Users should verify their installed version before assuming the key works. Run:

The public issue places the setting in 2.1.290, while one user explicitly confirmed it in 2.1.291. Organizations with managed installations may also receive updates on a controlled schedule.

The feature’s server-side gate adds another reason for caution. Setting idleCompaction to true does not necessarily force Anthropic to enable the feature for every account or environment. It permits the client behavior when other eligibility conditions apply.

Setting it to false is the relevant control for users who need an opt-out. Teams should still test the behavior under their own installation, account type, and policy hierarchy.

A managed setting can take precedence over a user choice. That is appropriate for organizations with central configuration, but it means editing one local file may not produce the expected result.

The safest verification method is behavioral. Confirm the client version, inspect effective settings, and test with a noncritical session before relying on the option during important work.

Users should also preserve durable instructions outside conversational history. Anthropic recommends placing persistent rules in CLAUDE.md, which Claude Code loads as project context. That advice applies whether idle compaction is enabled or disabled because ordinary near-limit compaction can still occur.

A searchable engineering knowledge base can serve a related purpose for human teams. Decisions, constraints, and investigation results become recoverable artifacts instead of depending entirely on one agent session.

The 200K Threshold Is Adjustable, but It Is Not a Context Limit

`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` changes when a session qualifies for idle compaction, not how large the model’s context window becomes.

Hallie said the minimum defaults to 200,000 tokens. Users can provide a different whole-number value through the environment configuration in Claude Code settings.

For example:

This example raises the eligibility threshold to 400,000 tokens. It does not grant a larger context window, reserve 400,000 tokens for conversation history, or guarantee that compaction fires immediately at that point.

The public issue analysis reported a lower bound of 100,000 tokens. Values beneath that floor were described as being raised to 100,000. Anthropic had not fully documented the environment variable in the public settings reference when the discussion unfolded, so users should treat implementation details as version-sensitive.

Raising the threshold favors fidelity. More large sessions can sit idle without being summarized, although returning after cache expiration can require more input processing.

Lowering the threshold favors cache efficiency. More sessions become eligible for pre-expiration compaction, increasing the chance that users return to summaries instead of full conversational history.

The right value depends on workflow shape, not simply model capacity. A long session with repetitive tool output may summarize cleanly. A shorter architecture discussion may contain dense, interdependent decisions that resist compression.

Token count measures size, not semantic importance. A 300,000-token debugging session could include thousands of disposable log lines. A 120,000-token security review could contain numerous precise threat assumptions that should remain verbatim.

This is why a configurable minimum helps without resolving the core tension. It lets teams choose where the tradeoff begins, but a numerical threshold cannot recognize whether the current conversation is safe to summarize.

Developers can reduce risk by creating explicit checkpoints before leaving a session. Ask Claude to record the active goal, confirmed findings, rejected approaches, changed files, test status, and next command in a repository note.

That note should not merely restate the task. It should capture the evidence required to resume without reconstructing the entire conversation.

Persistent constraints belong in CLAUDE.md or another authoritative project file. Temporary discoveries belong in an issue, work log, or handoff document. Generated summaries can then support continuity without becoming the only record.

Teams can also use /context to inspect what is consuming the active window. If bulky command output dominates, clearing or restructuring that material may be safer than allowing a general summary to decide what matters.

Manual /compact remains useful at natural boundaries. Anthropic says users can add focus instructions, which gives the summarizer a better preservation target than an unattended idle event.

The larger principle is simple: choose compaction around task boundaries when possible. Token thresholds prevent failure, but human-defined boundaries better reflect the structure of engineering work.

What Claude Code Compaction Preserves and What It Cannot Promise

Compaction preserves a working representation of the session, not a lossless copy of its reasoning history.

Anthropic’s Claude Platform documentation defines compaction as replacing older conversation turns with a model-written summary. Its compaction overview explains that applications continue by placing the returned compacted block where summarized messages previously appeared.

Claude Code handles that workflow inside the product. The precise implementation differs from an application directly using the Claude API, but the conceptual result is similar: older input is represented by generated text.

A good summary can retain the user’s request, current implementation state, important file paths, test results, and remaining tasks. It can drastically reduce the amount of prior material sent on later turns.

It cannot guarantee verbatim retention of every exchange. The summarizer must select information, organize it, and express it within a smaller token budget.

Reasoning history poses a particular challenge. A coding session often contains a chain of eliminations. Claude examines one file, forms a hypothesis, sees contradictory output, and changes direction.

The final summary may record the accepted explanation while compressing the path that validated it. That is often sufficient, but it weakens the next model’s ability to audit the conclusion.

Tool output creates another problem. Logs, compiler errors, database plans, and test traces can contain small details whose importance becomes apparent only later. A summary produced before that later discovery cannot know which line will matter.

User corrections can also lose force. “Do not change the schema” may appear once, followed by hundreds of turns. If it is not promoted into persistent instructions, compaction can reduce or omit its prominence.

Claude Code’s documentation explicitly recommends CLAUDE.md for rules that must survive. It also supports a “Compact Instructions” section, which tells the summarizer what to retain during compaction.

Those mechanisms reduce risk but do not make summaries lossless. A compact instruction is still guidance to a model performing selection. A project instruction file is stronger because Claude Code can load it again as authoritative context.

Developers should therefore divide session knowledge into three classes. Permanent operating rules belong in project instructions. Verified engineering state belongs in files or tracked work records. Conversational exploration can remain in the transcript and accept eventual compression.

This approach also improves collaboration. Another engineer cannot reliably inherit the undocumented nuance of a private agent conversation. A concise handoff file gives both humans and agents a shared recovery point.

The practical question is not whether summaries are good or bad. It is whether a particular fact can safely exist only inside a summary.

If losing a detail would cause an unsafe migration, repeated incident, or invalid result, record it outside the conversation before leaving the session.

Three Signals Will Show Whether Idle Compaction Earns Trust

The next test is whether Anthropic can make the efficiency benefit observable without making session continuity unpredictable.

The first signal is official documentation. Users need a stable description of eligibility, timing, supported versions, threshold limits, settings precedence, and interactions with prompt-cache policies.

Documentation would also clarify whether the 200,000-token default applies consistently across models and accounts. If Anthropic documents the environment variable and its lower bound, teams can configure it without relying on issue archaeology.

That outcome would strengthen confidence in the feature. Continued reliance on social posts and binary inspection would weaken it because undocumented controls can change without an obvious migration path.

The second signal is distinct hook metadata. A dedicated idle trigger would let teams treat timer-driven compaction differently from both manual /compact commands and near-limit automatic compaction.

Organizations could snapshot state before an idle event, attach tailored compact instructions, or record telemetry about how often the feature activates. Clear event identity would also make incident investigation easier.

If Anthropic keeps both automatic paths under the same auto label, administrators will have limited visibility into why a session changed. That would preserve a gap between the terminal experience and automation interfaces.

The third signal is evidence about summary quality in long coding sessions. User reports identify missing nuance, but the public discussion does not establish a general failure rate.

Useful evaluation would measure whether summaries retain explicit constraints, rejected hypotheses, pending tasks, test failures, file references, and safety rules. It should also test repeated compaction because errors can accumulate when one compressed state becomes input to another.

A positive result would support Anthropic’s efficiency argument. It would show that most qualifying sessions resume accurately enough to justify automatic compression before cache expiration.

A negative result would strengthen the case for opt-in behavior or higher default thresholds. It could also push Claude Code toward partial compaction that keeps recent turns verbatim while summarizing older material.

For now, developers have a workable choice. Keep Claude Code idle compaction enabled when lower resume overhead matters more than verbatim continuity. Raise the token threshold when only very large sessions justify the tradeoff.

Disable it with "idleCompaction": false when a paused session must return with its existing active history intact. Normal context-limit compaction can remain enabled as a separate safeguard.

Whichever policy you choose, do not make a long chat the sole record of critical engineering state. Put durable constraints in project instructions, preserve verified findings in files, and create a handoff before stepping away.

Claude Code idle compaction exposes a basic truth about coding agents: session continuity is not the same as perfect memory. Before your next long break, decide which one your workflow actually requires.