Claude Code Auto-Compact: When It Runs, What Stays

As a Claude Code session nears its context limit, auto-compact takes over. Claude Code clears older tool outputs first, then summarizes the conversation if it still needs room, and the session keeps going. Claude Code auto compact is on by default, and the "Context left until auto-compact" warning is your heads-up that it's close.

What to know, as of September 2026:

• It runs at a fixed point you can move. Use /autocompact 500k, the --autocompact flag, or an environment variable.
• You can turn it off, either in /config or with DISABLE_AUTO_COMPACT=1. The manual /compact keeps working either way.
• Some things survive it and some don't. Project instructions come back from disk. Path-scoped rules, and most of the files you've read, come back only when something triggers them again.

What "context left until auto-compact" means

That warning isn't a usage limit. Anthropic's cost guide says it means your conversation is getting close to the session's auto-compact window, which is the point where Claude Code summarizes older history to make room. So it's counting down to a summary, not to an error.

Here's a trap if you track context in a custom status line. The used_percentage field always measures against the model's full context window, not the auto-compact window. The environment variable reference warns that once CLAUDE_CODE_AUTO_COMPACT_WINDOW is set, that percentage stops telling you when compaction will happen. Because the percentage always counts against the full window, the same goes for any custom window. On a 1M model set to compact at 500K, your status line reads about 50% right when auto-compact fires.

For the real picture, run /context. It shows a breakdown of what's using the window, with suggestions for context-heavy tools and memory files.

When auto-compact runs by default

With no window set, Claude Code compacts when the conversation hits the model's context limit. The model configuration docs list the exceptions:

The cloud-provider row explains a common puzzle. The same Opus model compacts at 200K on Bedrock and much later on the Anthropic API, because the window depends on the platform, not the model. The Claude Code 1M context guide covers which setups get the big window.

How to change the auto-compact threshold

You can set the window in three places. Each one below beats the one before it:

1. /autocompact <value> applies to this session and later ones. It saves autoCompactWindow to your user settings. Run it with no value to see the current window, or run /autocompact auto to go back to the default for your model. It needs v2.1.221 or later, so check how your build updates in how to install Claude Code if the command is missing. If a higher-priority scope, such as managed settings, already sets the key, your value is saved but that scope's window still applies, and the command tells you.
2. --autocompact at launch overrides your saved setting for one run and leaves the setting alone. Managed settings can override /autocompact, but they can't override the flag.
3. CLAUDE_CODE_AUTO_COMPACT_WINDOW is meant for scripts and cloud environments. While it's set, it beats everything else, and /autocompact just reports the override.

The command and the flag accept 100K to 1M tokens, written as 200000, as 500k or 1M, or as a bare number from 100 to 1000 meaning thousands. The environment variable is stricter. It takes only a plain integer, so CLAUDE_CODE_AUTO_COMPACT_WINDOW=500k reads as 500 and clamps to the 100K minimum. That's an easy way to end up compacting constantly without knowing why. Whatever you set, Claude Code caps it at the model's real window.

There's also CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, a percentage from 1 to 100 of the auto-compact window. It can only lower the trigger point. Values above the default are ignored, and it only applies in sessions that compact before the model's limit.

How to turn Claude Code auto compact off

• /config → Auto-compact switches it off and writes "autoCompactEnabled": false to your user settings.
• DISABLE_AUTO_COMPACT=1 switches it off for one session. If either one turns auto-compact off, the other can't turn it back on.
• DISABLE_COMPACT=1 goes further and disables manual /compact too.

With auto-compact off, a full session stops with Context limit reached · /compact or /clear to continue until you make room. It's worth doing if you'd rather pick the moment, and the focus, yourself.

What survives compaction

Anthropic's context window walkthrough lists what happens to each kind of content:

Three things follow from this table.

Path-scoped rules aren't permanent. A rule with paths: frontmatter goes into message history when a matching file is read, so compaction summarizes it away like any other message. If a rule has to survive, remove the paths: frontmatter or move the rule into the project-root CLAUDE.md.

Only five files come back. Right after compacting, Claude Code re-reads up to five of the files touched in the session, picking the most recently modified. Everything else stays out of context until it's read again. A file over 5,000 tokens comes back as a path reference, shown as Referenced file instead of Read, though its rules still reload.

Long skills lose their endings. Truncation keeps the start of the file, so put the instructions that matter at the top of SKILL.md. Our Claude Skills guide covers the format.

How to keep what matters through a compaction

Give the summary a focus. Running /compact focus on the auth bug fix before a long new task means the summary keeps what you chose, not what the automatic pass guesses.

Write standing instructions. The docs suggest a "Compact Instructions" section in CLAUDE.md to steer what compaction keeps, so you don't have to retype a focus:

# Compact instructions

When you are using compact, please focus on test output and code changes

Re-inject the essentials with a hook. The hooks guide shows a SessionStart hook with a compact matcher, set in .claude/settings.json. Whatever it prints lands back in context after every compaction:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "git log --oneline -5" }]
      }
    ]
  }
}

Summarize only part of the session. /rewind can compress everything before or after a message you pick and leave the rest as it was. Reverting changes in Claude Code walks through that menu.

When compacting is the wrong move

Compaction has a cost. The cost guide points out that /compact has to read the whole conversation it's summarizing, so compacting a big context is a big request in itself. /clear costs nothing. If you're switching from a bug fix to something unrelated, clear.

For large files, send a subagent to read them. The file contents stay in the subagent's context window, and only its summary comes back to yours.

Watch for one error in particular: Autocompact is thrashing. It means compaction worked, but a huge file or tool output filled the window again right away, several times in a row, so Claude Code stopped retrying. The troubleshooting docs suggest reading that file in chunks, running /compact with a focus that drops the big output, or moving the work to a subagent.

A setup that compacts on your terms

You usually learn this after losing a rule mid-task. Taku is for the other way round: mirror a setup somebody already tuned into your own desktop workspace, run it, and adjust from there. Taku is in Beta, and the Mac app is available now.