When does Claude Code auto-compact a session, and how do you make it compact earlier with /autocompact or its overrides?
answer
- the model's limit, with exceptions
- about 967K on native 1M
- command, flag, setting, variable
- the variable wins over all
basics
~10 sBy 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 sWithout 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# 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
claudego deeper
Recall that Claude Code compacts on its own near the limit and that /autocompact with a size such as 500k makes it compact earlier.
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.
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.
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.