skip to content

When does Claude Code auto-compact a session, and how do you make it compact earlier with /autocompact or its overrides?

level: middleimportance: should knowfreq 9%

answer

  1. the model's limit, with exceptions
  2. about 967K on native 1M
  3. command, flag, setting, variable
  4. the variable wins over all

basics

~10 s

By default Claude Code auto-compacts when the conversation reaches the model's context limit, or about 967K tokens on native 1M-window models. /autocompact 500k, --autocompact, autoCompactWindow or CLAUDE_CODE_AUTO_COMPACT_WINDOW sets an earlier window.

solid answer

~40 s

Without a configured window, Claude Code compacts when the conversation reaches the model's context limit, with documented exceptions: models running a native 1M window, such as Sonnet 5 on the Anthropic API, compact at about 967K tokens, and Opus 4.6 or Sonnet 4.6 without `[1m]` compact at the 200K boundary. To compact earlier, run `/autocompact 500k`, which saves the window to your user settings and applies it now; `/autocompact auto` returns to the tuned window. `--autocompact` overrides it for one launch, `autoCompactWindow` sets it in a settings file, and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats all three. Values run from 100K to 1M and are capped at the model's window. `autoCompactEnabled: false` or `DISABLE_AUTO_COMPACT=1` turns the automatic pass off while keeping `/compact`; `DISABLE_COMPACT=1` turns off both.

code

bash · 7 lines
bash
# One launch at a 400K window; saved settings stay unchanged
claude --autocompact 400k

# Scripts and cloud environments: wins over the command, flag and setting.
# Plain integer only: "400k" would read as 400 and clamp to 100000.
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000
claude

go deeper

for a junior

Recall that Claude Code compacts on its own near the limit and that /autocompact with a size such as 500k makes it compact earlier.

for a middle

Explain the defaults per model, including about 967K on native 1M windows and 200K without extended context, and the precedence of command, flag, setting and environment variable.

for a senior

Show operational judgment: pick a window below a gateway's real limit, avoid the 500k env-var trap, and know that disabling auto-compact turns a full window into a hard stop.

for a principal

Weigh a fixed, earlier window set in managed settings or the environment against per-developer tuning, trading summary loss against long-session drift across a team.

## What auto-compaction is **Auto-compaction** is Claude Code's automatic version of `/compact`. As a conversation approaches its limit, Claude Code first clears older tool outputs, then summarizes the history if it still needs room. A full window therefore does not end the session. The **auto-compact window** is how full the context may get before that pass runs. ## Default thresholds If you set nothing, Claude Code compacts when the conversation reaches the model's context limit, except in these cases: - **Native 1M-window models** compact before the window fills, at about 967K tokens. On the Anthropic API these include Sonnet 5, the Fable models and Opus 4.7 and later. Fable models, Sonnet 5 and later, Opus 4.6 and later, and Sonnet 4.6 all support a 1M window; Opus 4.6 and Sonnet 4.6 reach it only through their `[1m]` variant. - **Opus 4.6 and Sonnet 4.6 without extended context** compact at the 200K boundary. - **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`** holds native 1M models to 200K, and they compact there. - **Cloud sessions** compact as the conversation approaches the limit. - **An unrecognized model ID**, such as a gateway alias, compacts at the window Claude Code assumes for it. ## Four ways to set the window | Control | Scope | Precedence | |---|---|---| | `/autocompact <size>` | Saved to your user settings and applied now | A higher settings scope, such as managed settings, can override the saved value | | `--autocompact <size>` | One launch; saved settings unchanged | Overrides the setting for that launch | | `autoCompactWindow` | Any settings file | Overridden by the flag and the variable | | `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Environment, for scripts and cloud environments | Wins over the command, the flag and the setting | The command and flag accept 100K to 1M tokens as a plain count (`200000`), a `k` or `M` suffix (`500k`, `1M`), or a bare number from 100 to 1000 meaning thousands. The environment variable accepts **only a plain integer**: `500k` reads as `500` and clamps to the 100K minimum. Every form is capped at the model's context window, so a larger value cannot stretch a 200K model. `/autocompact auto` and `--autocompact auto` return to the window tuned for your model, and `/autocompact` with no argument opens a dialog showing the current window. While the variable is set, `/autocompact` reports the override instead of changing anything. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is a second, coarser lever: a percentage of the auto-compact window at which compaction triggers. It can only lower the threshold, and values above the default are ignored. ## Turning it off 1. `autoCompactEnabled: false`, the **Auto-compact** toggle in `/config`, stops the automatic pass. 2. `DISABLE_AUTO_COMPACT=1` does the same for a session; whichever of the two turns it off, the other cannot turn it back on. 3. In both cases manual `/compact` still works. `DISABLE_COMPACT=1` disables automatic compaction **and** `/compact`. With the automatic pass off, a full window ends a turn with `Context limit reached · /compact or /clear to continue`, and the line says auto-compact is off when a `/config` change would turn it back on. ## Why compact earlier A 1M window is capacity, not a promise of quality. A long session can degrade well before it is full, so some developers prefer a summary at 400K to a quiet slide toward 967K. Teams behind an LLM gateway that rejects requests above 200K set `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`, because Claude Code gives recognized models their Anthropic API window and cannot detect the gateway's lower limit. A sensible way to choose a value: 1. Note where quality starts to slip in your long sessions, using `/context` to read the window size at that point. 2. Set `/autocompact` a little below it, for example `/autocompact 400k`, and watch whether summaries arrive at natural breaks. 3. For CI or shared cloud environments, pin the value with `CLAUDE_CODE_AUTO_COMPACT_WINDOW` so every run behaves the same. One measurement trap: a status line's `used_percentage` always measures against the model's full window, so once you set a smaller auto-compact window that percentage no longer tells you when compaction will run. ## Version notes `/autocompact` and `--autocompact` need Claude Code 2.1.221 or later. At 2.1.286 `/autocompact` saved one window for every model, as the top-level `autoCompactWindow` in user settings. From 2.1.288 it saves the window per model under `modelSettings`, so each model keeps its own value when you switch.

  • You export CLAUDE_CODE_AUTO_COMPACT_WINDOW=500k and Claude Code sessions now compact very early. Why?
    The environment variable takes only a plain integer. `500k` reads as `500`, which is below the 100K minimum, so the window clamps to 100,000 tokens. Write `500000`. The `k` and `M` suffixes work only for `/autocompact` and `--autocompact`.
  • Why would a team behind an LLM gateway set the auto-compact window to 200000?
    Behind a custom `ANTHROPIC_BASE_URL`, Claude Code gives recognized models the window they have on the Anthropic API, 1M for Opus 4.7 and later, Sonnet 5 and later and Fable. It cannot detect a lower limit the gateway enforces. Setting `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` makes sessions on every model compact at that boundary instead of failing.
  • Does a status line's context percentage tell you when Claude Code will compact?
    Not once you set a smaller window. The status line's `used_percentage` always measures against the model's full context window, while compaction follows the auto-compact window. With a 1M model and a 400K window, compaction runs near 40% on that meter.

  • Setting autoCompactWindow above the model's window lets a 200K model run longer
  • DISABLE_AUTO_COMPACT=1 also disables the manual /compact command
  • CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=95 makes compaction wait until 95% full
  • The --autocompact flag permanently rewrites the saved setting
  • /autocompact overrides the CLAUDE_CODE_AUTO_COMPACT_WINDOW variable

Assumes Claude Code 2.1.286; /autocompact needs 2.1.221 or later, and 2.1.288 changed it to save a window per model under modelSettings.