Claude Code Auto-Compact Threshold Is Your Window Minus 33K

Every few days someone asks the same question in a different way: at what point does Claude Code stop working and start summarizing? The official docs answer it for exactly one model. Sonnet 5, they say, auto-compacts at about 967K tokens by default. That number is useless on its own, because it does not tell you the rule that produced it.

So I measured the rule. Then I went looking through 2,883 transcript files on this machine to see how often the threshold had actually fired on the unattended jobs that publish this blog. The answer to the second question turned out to be more interesting than the answer to the first.

The threshold is your window minus a fixed 33K

Claude Code ships two commands that report context state, /context and /autocompact. Both carry supportsNonInteractive in the binary, so both run under claude -p. They cost nothing: every probe below returned num_turns: 0, total_cost_usd: 0, and finished in 19–1,111 ms. That makes a sweep cheap.

I ran /context ten times from a scratch directory, varying only CLAUDE_CODE_AUTO_COMPACT_WINDOW, with the same 21.5K of baseline context loaded each time.

Env value	Effective window	Autocompact buffer	Buffer as %	Free space
50,000	100k (clamped up)	33k	33.0%	45.5k
100,000	100k	33k	33.0%	45.5k
150,000	150k	33k	22.0%	95.5k
200,000	200k	33k	16.5%	145.5k
300,000	300k	33k	11.0%	245.5k
400,000	400k	33k	8.3%	345.5k
500,000	500k	33k	6.6%	445.5k
800,000	800k	33k	4.1%	745.5k
1,000,000	1m	33k	3.3%	945.5k
2,000,000	1m (clamped down)	33k	3.3%	945.5k

The buffer is a constant, not a percentage. It sits at 33K whether the window is 100K or a million, which is why the percentage column slides from 33% down to 3.3% while the token figure never moves. The arithmetic closes on every row: at the 200K setting, 200 minus 21.5 of loaded context minus 33 of buffer leaves the 145.5K the command reports as free.

Both ends clamp. Asking for 50,000 gives you 100K, and asking for two million gives you the model's own window. The CLI states the range when you push past it, rejecting --autocompact 50k with "It must be 'auto', or between 100k and 1M", which matches the model configuration docs word for word.

That gives a rule you can apply to any configuration: threshold = min(your window, the model's window) − 33,000. Check it against the one published number. A million minus 33,000 is 967,000, and the docs say Sonnet 5 compacts at about 967K. The constant I measured on a different model reproduces Anthropic's figure exactly.

On the default, nothing is reserved at all

The sweep hides something until you compare it against an unset variable. My fleet runs claude-opus-5[1m], so I ran /context once with the window explicitly set to 1,000,000 and once with nothing set. Same model, same million-token window, same baseline.

With the variable set, free space reads 945.5K and an Autocompact buffer row appears at 33K. With it unset, free space reads 978.5K and the buffer row is gone. The window did not change. The only thing that changed was which input decided the window.

The docs describe this outcome plainly, in a sentence that is easy to skim past: "If you don't set an auto-compact window, Claude Code compacts when the conversation reaches the model's context limit." Not before it. At it.

The binary is blunter. The SDK schema for the worker's auto-compact state defines an enforced flag as "Whether threshold-triggered compaction will actually fire at threshold. False when the worker defers to the API's prompt-too-long (reactive mode) … clients then show % of window used instead of a countdown to a compaction that won't happen." The same schema defines the threshold itself as "effective_window minus the summary buffer", and lists the inputs that can decide a window as env, settings, clientdata, experiment, model-default, unknown-model, and auto.

There is no flag in that list, which explains a small oddity I hit while testing: --autocompact 300k reports its window as coming "from settings" even though my settings.json has no compaction key and its modification time never moved.

2,883 transcripts, zero automatic compactions

Knowing the rule is one thing. I wanted to know whether it had ever bound in practice, so I scanned every session file under ~/.claude/projects and counted compact_boundary records. The corpus: 2,883 files, 244,421 records, 684.4 MB, 2,840 sessions across 16 projects and 8 client versions, with records running from 2026-06-16 to this morning. The technique for reading these files is the same one I used to count token usage from Claude Code transcripts, where the per-content-block duplication matters.

Two compaction events. Both trigger: "manual". Automatic compactions: none.

Timestamp (UTC)	Trigger	preTokens	postTokens	Reduction	Duration
2026-07-28T09:46:21Z	manual	980,030	11,030	98.87%	176,498 ms
2026-07-29T08:21:55Z	manual	799,151	11,593	98.55%	180,319 ms

Both records belong to one interactive session, and that session is also the largest in the corpus, peaking at 978,410 tokens. The single conversation that ever came close to filling a million-token window is the same conversation where a person typed /compact, twice, each time waiting about three minutes for a summary that discarded roughly 98.9% of the context. Compaction is expensive by construction, as the cost docs note: "/compact reads the conversation it summarizes, so compacting a large context is itself a large request."

What the distribution says about scheduled runs

Across 2,436 sessions with a non-zero context measurement, the median peak was 51,086 tokens and the 99th percentile was 218,213. Nothing reached a million. Narrowing to the 221 headless runs that belong to this blog's ten-slot unattended harness, the median peak rises to 145,601 tokens, about 2.85 times the median across all headless work on this machine, because a publishing slot spends its life reading sources.

Run those peaks against the rule and the picture inverts depending on deployment:

• Default window on Opus 5 with 1M context: 0 of 221 blog runs would compact.
• A 200K window, which is what the docs say Opus 5 gets on Bedrock, Google Cloud's Agent Platform and Microsoft Foundry: threshold 167,000, and 79 of 221 runs (35.8%) would cross it.

Same prompts, same jobs, same code. Moving this workload to a 200K deployment would introduce a mid-run summarization step into more than a third of publishing slots, each one silently rewriting the research the run had already gathered. That is the practical reason to know your threshold: it is a property of where you deployed, not of what you asked for.

Reading your own numbers

Two commands, no tokens, no turns:

# which input decided your window, and whether it is capped
claude -p "/autocompact"

# the full breakdown, including the Autocompact buffer row if one exists
claude -p "/context"

If /context shows no Autocompact buffer row, no proactive threshold is being enforced for your session, and the percentage you see is a percentage of the window rather than a countdown. Setting a window with /autocompact 200k, the --autocompact flag, or the environment variable makes the buffer appear. It is the same trick as reading the remaining usage limit from a script, where the readable surface turned out to be open to headless runs even though the structured one was not.

Worth saying clearly: none of this shows auto-compaction failing. It shows that on a million-token window my jobs never get near the ceiling, so a mechanism I had assumed was quietly managing my context has in fact never run. The thing I had been budgeting for was not the thing costing me anything.

The prompts and the launchd wiring behind those ten slots are packaged in the Playbook if you want the harness that generated this corpus.

Sources and limits. The threshold rule comes from ten /context probes on this machine against claude-opus-5[1m], client 2.1.227, one run per window size from a single scratch directory with the same 21.5K baseline, so the sweep controls the window and nothing else. The 33K buffer is the value /context prints, which is rounded for display; I treat the match with Anthropic's published 967K figure for Sonnet 5 as corroboration rather than proof of the exact constant. The transcript corpus is one machine's history, 2026-06-16 to 2026-08-15, and Claude Code deletes session files on a 30-day schedule I measured separately, so "zero automatic compactions" means zero within that observable window and not for all time. I never read the enforced field directly; it is emitted by SDK workers on a path my setup does not use, so I inferred its effect from the presence or absence of the buffer row and from the schema text in the 2.1.227 binary. For the same reason I have never watched reactive compaction actually run, having never filled the window. The --autocompact flag reporting its source as settings is my reading of an enum that has no entry for the flag. Quotations are from the Claude Code model configuration and cost management docs, read on 2026-08-15, and from issue #28728, which asked for a configurable threshold in February and was closed as not planned before the window controls described here shipped.