Harnesses
Claude Code's 54-minute rule: what idle compaction keeps, what it drops, and how to turn it off
Leave a Claude Code session over 200,000 tokens alone for about 54 minutes and it will come back as a summary. The behaviour has been in the client since v2.1.286, went into the release notes on 14 October 2026, and picked up an off switch two days later. Here is what actually survives a compaction, what the month of user reports shows, and how to set the rule per project.
- Published
- 02 Nov 2026
- Reading
- 9 min
- Class
- harnesses
half-life 90dfrom 2 Nov 2026
The message reads: “Compacted while idle, before the prompt cache expired.” You went to lunch with a session holding two hundred thousand tokens of instructions, file reads and decisions, and came back to a few paragraphs of summary written in your absence. Nothing crashed. The transcript is still on your disk. But the model that answers your next message has never seen most of what you are about to refer to.
This is idle compaction, and it is the default. Claude Code's prompt cache lasts one hour; a conversation that sits quiet for roughly 54 minutes and is over 200,000 tokens gets summarised before that cache lapses, so the next message does not reprocess the whole history at full price (v2.1.299 release notes, 14 October 2026). It is a cost decision that has become a workflow decision, and it is worth understanding exactly before you either rely on it or turn it off.
How this shipped: quietly first, then loudly
The order matters, because it explains the anger in the issue threads. The feature shipped behind a server-side flag before it had a setting or a release note. Users first saw it fire from v2.1.286; the code itself had been sitting in builds from v2.1.283, and a server-side gate decides whether it runs at all (timeline assembled from issue #98747, opened 1 October 2026, and issue #105775, opened 28 October 2026, both read 2 November 2026).
- 1 October 2026 — A developer who keeps around 20
parallel Claude Code sessions reports that seven of them were compacted
overnight, none close to the context limit. The exact instructions,
the reasons behind decisions and the methods agreed on were gone from
what the session could see; the reporter rebuilt the grounding by hand
from the transcripts still on disk. The compactions were logged in the
transcript with a trigger of
manual, although nobody had run/compact. The issue drew more than 30 reactions. - 2 October 2026 — An Anthropic collaborator answers in the thread: a setting is coming, and the behaviour is currently limited to contexts of 200K tokens and above.
- 14 October 2026 — v2.1.299 puts it in writing:
“Added idle compaction in the terminal: a 200K+ token conversation
left idle for about 54 minutes is compacted before its one-hour prompt
cache expires, so your next message doesn't reprocess it all.” The
same entry adds
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENSto move the 200K floor and"idleCompaction": falseinsettings.jsonto turn it off — both requiring v2.1.290 or later. - 16 October 2026 — v2.1.302 adds an
Idle compaction row to
/config, and the notice printed after a compaction now says how to disable it. - 19 October 2026 — v2.1.304 improves what comes back: the compaction summary in the transcript view now names the tools called before it ran, and Claude is sent the skill list again afterwards rather than being left with a stale one.
- 30 October 2026 — v2.1.314 extends the same behaviour to VS Code and Claude Desktop's Code tab: a 200K+ token conversation left idle is summarised, and the summary is used on the next message if the prompt cache has expired.
So the trajectory is: shipped silently, complained about, documented, given a switch, then widened to the editors. As of 2 November 2026 the latest release is v2.1.316 (31 October), which does not change the behaviour.
What the 54 minutes actually measures
The timing is not arbitrary. On 3 October 2026 a developer in the #98747 thread read the v2.1.287 binary and published what it does, which matches the release note: the timer only arms when the session's prompt cache has a one-hour lifetime, and it fires 90 per cent of the way from your last activity to cache expiry — about 54 minutes of quiet. It considers contexts of 200,000 tokens or more (the server can lower that; the floor is 100K), and it skips the run if it would fire more than 60 seconds late, the cache is already cold, a newer request has landed, another process holds the session, or the rate-limit state does not allow it.
Three consequences follow from that. The feature only exists where the cache lasts an hour, so a gateway or configuration with a different cache lifetime changes the maths. The threshold can be lowered remotely, which is why what you observe on your version is not always what your version's notes describe. And a second mode exists that writes the summary in the background while you are away and swaps it in when you return — described by the reporter of #105775 on 28 October 2026 as a server-side choice between modes.
The cost argument is real and simple. Once the cache is cold, the next message reprocesses everything at full input price; summarising first means the next message processes a few thousand tokens instead. What Anthropic has not published is a figure for how much that saves, so the benefit in your account is something you measure, not something anyone has benchmarked.
What survives a compaction — and what does not
Anthropic's own context-window documentation keeps a table of this, and it is the most useful thing you can read before deciding anything (Explore the context window, read 2 November 2026). Condensed:
| Content | After compaction |
|---|---|
| System prompt and output style | Both still apply |
| Project-root CLAUDE.md and unscoped rules | Re-injected from disk |
| Auto memory | Re-injected from disk |
| Skill descriptions | Rebuilt and re-injected (v2.1.304 or later) |
| Plan written in plan mode | Re-injected from disk |
| Files Claude read or edited | Up to five re-read, most recently modified first; anything over 5,000 tokens comes back as a path reference, not its contents |
| Invoked skill bodies | Re-injected, capped at 5,000 tokens per skill and 25,000 in total, oldest dropped first |
Rules with paths: frontmatter, nested CLAUDE.md files | Summarised away with the conversation |
| Context that hooks added earlier | Summarised away |
SessionStart hooks matching the compact source | Run, and their output is added to the compacted context |
| Background commands and subagents | Keep running; Claude is reminded which ones, so it does not start duplicates |
Source: Claude Code context-window documentation, “What survives compaction”, read 2 November 2026.
Read the two halves against each other. Anything you wrote down as project
instructions in the root CLAUDE.md comes back untouched; anything you enforced
with a paths:-scoped rule or a nested CLAUDE.md in a subdirectory
does not, because those load on demand when a trigger file is touched and are
summarised away with everything else. The documentation's advice is blunt:
if a rule must survive compaction, drop the paths: frontmatter or
move it to the project-root CLAUDE.md. The same applies to whatever a
SessionStart hook injected three hours ago — that is conversation,
not configuration. This is the practical edge of
context engineering: what lives
in a file the harness re-reads survives; what lives only in the thread does
not.
The conversation history itself becomes a summary, and the summary is written
while you are away, so it reflects what looked important at that moment rather
than what you need now. Claude re-reads up to five recently touched files to
recover, but a file over 5,000 tokens comes back as a path only — the model
sees Referenced file instead of the content, so a big file you
were reasoning about is no longer in the window
(context-window docs,
read 2 November 2026). The full transcript stays on disk, which is why the
reporter of #98747 could rebuild anything at all: recovery is possible, but it
is manual and it is your job.
A month of reports: what people are actually objecting to
Two issues carry the argument, and it is worth separating what is measured from what is asserted.
- The switch arrived after the behaviour. #98747 (1
October 2026) was about silence: no warning, no opt-out, and a trigger
mislabelled as
manualthat made the change hard to diagnose. It was closed once the setting shipped. The thread also records that idle compaction does firePreCompact, which is what makes the workaround below possible, and that v2.1.290 corrected the trigger label toauto— a distinctidlevalue is still an open request. - The choice prompt is gone. #105775 (28 October 2026,
still open on 2 November) points out that returning to a long
conversation used to offer three options — compact, start a new session,
or continue — and now compaction simply happens. Turning
idleCompactionoff does not bring the choice back; it only stops the timer, so the only way to decide is to remember to type/compactyourself. There is no equivalent toggle in the desktop app yet. - One developer's logs, on size. The same reporter audited their own Max-plan history: before 26 October 2026, automatic compactions happened only when the window was genuinely full, at around 967K tokens; from 26 October, sessions were compacted at 200K to 480K after breaks of 99 minutes or overnight, one session three times in eight hours. Across 142 recorded compactions the result was always roughly 30K to 45K tokens — three or four per cent of a full window — against the 100K to 200K they see Codex leave behind. These are one user's logs, not vendor data, but they are specific, dated and checkable against your own transcripts.
- The cost case is contested too. The same issue argues that re-onboarding the model after a compaction re-reads more than a plain cache rebuild would have cost, and ends with less context — for a heavy user, one cache rebuild after a break can be cheaper on both counts. Defenders in the earlier thread make the opposite case for large sessions left running all day. Neither side has published numbers.
The same lunch break costs less on Codex
Cache lifetime is the root cause, and the competitor spent the same week moving the other way. On 20 October 2026 OpenAI's changelog added 12-hour prompt caching to the API, with 12-hour cache writes priced at 2.5 times the input token price (OpenAI API changelog, entry dated 20 October 2026). The same day, OpenAI's Codex engineering lead Thibault Sottiaux posted that signed-in Codex and Work users keep their cache indefinitely — no penalty for coming back to an old conversation, and a guaranteed cache hit (post on X, 20 October 2026, cited in #105775).
Treat that claim at its weight. It was announced on social media, not written into the docs: OpenAI's own prompt-caching guide still says cache entries are not stored indefinitely and that a valid lifetime does not guarantee every request reuses stored state, and a verification write-up on 24 October 2026 found no Codex or Work documentation describing indefinite retention at all (claim vs verified, updated 24 October 2026). What is documented is the 12-hour API option and its price.
The comparison that matters for your working day: on one harness the answer to “I left a session for two hours” is a summary written in your absence, and on the other it is a warm cache and the same conversation. This is about caching, not memory — resuming cheaply is not the same as remembering more — but it changes which harness you should park work in overnight.
What to do about it
- Find out what your build does. Run
claude --version. The setting needs v2.1.290 or later, the/configrow needs v2.1.302 (16 October 2026), and VS Code and Claude Desktop need v2.1.314 (30 October 2026). Because the gate is server-side, check the/configrow rather than trusting the version number alone. - Decide per project, not globally. Leave it on for the big research or refactor session you walk away from, where a summary of hours of reading is genuinely a saving. Turn it off for orchestrator and stateful sessions where the decisions live only in the conversation — that is the workflow #105775 says is broken, and a summary written while you were away is the worst possible version of it.
- Set the two lines.
{"idleCompaction": false}in~/.claude/settings.json(everything) or your project's.claude/settings.json(just that repo). If you want to keep compaction but raise the floor, setCLAUDE_CODE_IDLE_COMPACT_MIN_TOKENSto something like500000in the same file'senvblock. From v2.1.302 both are also reachable from the Idle compaction row in/config. - Move non-negotiables into the root CLAUDE.md. It is re-injected from disk after every compaction. Path-scoped rules, nested CLAUDE.md files and anything a hook injected earlier are summarised away, so treat those as conveniences, never as instructions that must survive.
- Snapshot before it can happen. The #98747 thread
publishes a tested pair: a
PreCompacthook that writes recent prompts and edited files to disk, and aSessionStarthook withmatcher: "compact"that re-injects them. Hook output is capped at 10,000 characters, so trim to what matters. It fires for idle and manual compactions alike — the trigger label cannot yet tell you which one ran. - Compact on your own terms. The documentation offers
better tools than waiting for the timer:
/compact focus on the auth bug fixbefore a long break, so the summary keeps what you chose;/rewindwith summarise from or up to here for part of a conversation;/autocompact 500kto move the limit pass;/clearbetween unrelated tasks; and a subagent for large file reads, so only the summary returns to your window. - Keep the transcript. Session messages stay on disk and
--resumegets you back to them — the #98747 reporter rebuilt the context that had been summarised away from those on-disk transcripts. - If you split time with Codex, measure before you conclude. The 20 October cache changes make parking a session cheaper there, but the headline claim is undocumented. Compare your own usage across a week of returns rather than switching on the strength of a post.
What is not settled — as of 2 November 2026
- No published savings figure. Anthropic has not put a number on what idle compaction saves, and the counter-argument that re-onboarding costs more is equally unquantified. Both sides are reasoning from how caching works.
- #105775 is open. Four requests are unanswered: restore the compact / new session / continue prompt and make idle compaction opt-in, add a desktop toggle, offer longer cache retention, and keep the full pre-compaction conversation one click away.
- The trigger label is still ambiguous. v2.1.290 changed
the recorded trigger from
manualtoauto, but a distinctidlevalue — needed if you want hooks that react only to timer-driven compaction — has not shipped. - Behaviour can change without an update. The gate is
server-side, with off, log and compact modes reported in the thread. A
client version tells you what is possible; the
/configrow tells you what is on.
The honest summary: idle compaction is a sensible default with a bad rollout
and an incomplete set of controls. For most people it will save money and lose
nothing they needed. For anyone running long-lived sessions where the
conversation is the work — orchestrators, multi-hour refactors,
decisions recorded nowhere else — it is one settings.json line
away from being off, and the root CLAUDE.md is where the instructions you
cannot afford to lose belong either way. For how sessions accumulate context
in the first place, see harness
engineering and Claude Code mods.
Sources
- Claude Code v2.1.299 release notes — 14 October 2026. The idle compaction announcement,
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS,"idleCompaction": false, and the v2.1.290 minimum for both. - Claude Code v2.1.302 release notes — 16 October 2026. The Idle compaction row in
/configand the post-compaction notice explaining how to disable it. - Claude Code v2.1.304 release notes — 19 October 2026. Tool names added to the compaction summary; the skill list is re-sent after compaction; skill descriptions rebuilt on resume.
- Claude Code v2.1.314 release notes — 30 October 2026. Idle compaction extended to VS Code and Claude Desktop's Code tab.
- Issue #98747 — idle compaction silently discards working context — opened 1 October 2026, read 2 November 2026. Seven of ~20 sessions compacted overnight, the
manualtrigger label, Anthropic's 2 October reply, the 3 October reverse-engineering of the timer (90% of a one-hour cache window, 200K floor with a 100K server-side minimum, skip conditions, off/log/compact gate), and the testedPreCompact/SessionStartsnapshot recipe. - Issue #105775 — idle compaction removed the compact / new session / continue choice — opened 28 October 2026, open as of 2 November 2026. The mode that swaps in a summary written while you were away, compactions at 200K–480K from 26 October, 142 compactions leaving 30K–45K tokens, the Codex comparison, and the four unanswered requests.
- Explore the context window (Claude Code documentation) — read 2 November 2026. The “What survives compaction” table: project-root CLAUDE.md and auto memory re-injected from disk, up to five files re-read with the 5,000-token path-reference rule, skill bodies capped at 5,000/25,000 tokens, path-scoped rules and hook context summarised away, SessionStart hooks run.
- OpenAI API changelog — 20 October 2026 entry: 12-hour prompt caching, writes at 2.5 times the input token price.
- Thibault Sottiaux on X — 20 October 2026: cache kept indefinitely for signed-in Codex and Work users. Announced on X; cited in issue #105775.
- OpenAI 12-hour prompt caching: claim vs verified (explainx) — published 20 October 2026, updated 24 October 2026. What is documented in OpenAI's changelog and docs, what is only an X post, and the 24 October note that changing reasoning level no longer breaks the cache.
- Claude Code idle compaction: what it does and how to turn it off (Developers Digest) — last updated 17 October 2026, read 2 November 2026. The per-project recommendation and the report that orchestrator workflows broke when files were not re-read afterwards.
- Claude Code “Compacted while idle” guide (TurboAI) — read 2 November 2026. The 90%-of-the-hour timing and the ten-day gap between v2.1.283 and v2.1.290 with no off switch.
- Claude Code idle compaction saves cache, but resumes from a summary (Remio) — read 2 November 2026. The distinction between a stored transcript and the model's working context, and the three evidence levels for what is claimed about the feature.
- Related on this site: context engineering, harness engineering, Claude Code mods, anatomy of an agent harness.