// The guide

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

2026-07-16 · 5 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. 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

The binary reads an environment variable the docs never mention:

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40

It takes a value from 1 to 100. The verified semantics: the auto-compact threshold becomes floor(context window × n / 100) tokens, capped at the internal default (the window minus 13,000 tokens). So 40 means auto-compact triggers at roughly 40% of the context window used, instead of near the top.

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

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "40"
  }
}

Or export it in your shell profile. Either way it takes 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 variable is named as a test override. It can change or disappear in any release, without notice. It works on 2.1.211; 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.
• It only moves the automatic trigger. It does not change the window size, and it does not make summaries better. 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