← All posts

// The guide

Claude Code auto-compact: the threshold setting that actually exists.

2026-07-16 · updated 2026-08-01 · 6 min read · by Nabil BA-MOH

If you searched for a way to make Claude Code compact earlier, you probably found the same tip we did: add "autoCompactThreshold": 80 to your settings.json. We tried it. It does nothing. So we read the code Claude Code actually ships and found the knob that does work. Here it is, with the honest caveats.

Everything below was verified on Claude Code v2.1.211 by reading the shipped binary, not by quoting other blog posts — and re-checked on v2.1.220 on 2026-08-01. Version matters; re-check after big updates.

Auto-compact in one minute

Claude Code works inside a fixed context window. As a session grows, the window fills. When it gets close to full, auto-compact kicks in: the conversation is summarized, the summary replaces the history, and the session continues with room to breathe.

The catch is timing. By default, compaction fires near the ceiling. At that point the summarizer is working under pressure, with a nearly full window, and the summary loses more nuance than an earlier, deliberate one would. If you have ever watched Claude Code come back from a compact slightly dumber about your task, that is why.

So the question is legitimate: how do you move the trigger earlier?

The tip that doesn't work

A widely shared tip says to put this in settings.json:

{ "autoCompactThreshold": 80 }

That key does not exist as a setting. In the 2.1.211 binary, the string autoCompactThreshold appears only as an internal telemetry field — a name the app uses when reporting metrics, not a setting it reads. Nothing in the settings loader looks for it.

The trap is that it fails silently. settings.json accepts unknown keys without complaint, so you add the line, nothing breaks, and you assume it worked. It didn't. Your threshold never moved.

What's officially documented

The official settings docs give you exactly two switches, both on/off:

• autoCompactEnabled in settings.json. Boolean, default true. Set it to false and auto-compact never fires.
• The DISABLE_AUTO_COMPACT=1 environment variable. Same effect.

No threshold. Officially, auto-compact is all or nothing.

The knob that actually exists — it's a pair now

The binary reads two environment variables the settings docs never mention:

CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000   # your model's real context window
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40        # trigger at 40% of it

The rule: the auto-compact threshold becomes window × percentage / 100 tokens. With a 1M-window model and 40, auto-compact triggers around 400K tokens, instead of near the top.

When we first published this post, the percentage override alone was enough on the version we read (2.1.211). On current versions it is not: the override only applies when compaction runs in proactive mode, and a normal local session is proactive only when CLAUDE_CODE_AUTO_COMPACT_WINDOW is set too. Set the percentage alone and it is read, then ignored — the same silent failure we called out above, which is exactly why this update exists.

Two traps in the window value:

• It must match your model's real context window. Set it higher and the computed threshold lands beyond the real ceiling: proactive compaction never fires and you are back to compacting at the wall. As of August 2026: 1,000,000 for the current Opus / Sonnet / Fable generation, 200,000 for Haiku 4.5.
• It is static. Claude Code does not adapt it to the model you are actually running — there is no "auto" value and no per-model form. If you mix 1M and 200K models, set it per project in the project's .claude/settings.json rather than once globally.

To make the pair permanent, put both in the env block of ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "40"
  }
}

Or export them in your shell profile. Either way they take effect on new sessions, not the one currently running.

How the engine decides: warn, compact, blocked

Under the hood, Claude Code computes a level from the current token count. Three levels matter:

• warn — you are within 20,000 tokens of the threshold. The status line starts nudging you.
• compact — the threshold is reached. Auto-compact fires (if enabled).
• blocked — you are near the hard ceiling of the window. No more room.

The percentage in the status line and these levels are consistent with each other, so what you see is what the engine acts on. Lowering the override moves the whole ladder down: you get warned earlier and compacted earlier, far away from the blocked zone where summaries are at their worst.

The honest caveats

• This is undocumented. Inside the binary the percentage variable is named as a test override. It can change or disappear in any release, without notice — it already changed once between 2.1.211 and 2.1.220, which is what this update is about. Re-verify after you update.
• Lower is not better. Every compact costs a summarization pass and loses some nuance. Set it too low and you compact constantly, paying that price over and over. 40 to 70 is a sane range. We run 40. Also note the percentage is clamped at roughly 83: it can pull the trigger earlier than the default, never later.
• It only moves the automatic trigger. Despite its name, CLAUDE_CODE_AUTO_COMPACT_WINDOW does not grow your context window — it tells the compaction engine what the window is. The pair does not make summaries better either. It just buys them room.

The better habit: /compact on your terms

The override is a safety net, not a strategy. The best compaction is the one you run yourself: type /compact at a natural breakpoint — a task finished, findings written to a file, state saved. A deliberate compact with everything persisted beats any automatic one that lands mid-task, whatever the threshold.

The pattern that works: finish a chunk of work, persist what matters to disk, then compact. The override exists for the sessions where you forget.

New to Claude Code entirely? Start with our non-developer guide first.

FAQ