← All guides

Token usageWorkflow

Claude Code Auto-Compact: What It Does and How to Control It

By Neo Zino - builder of ClockedCode·Updated July 28, 2026·8 min read

Claude Code auto-compact summarizes your conversation once context nears its limit. Here is exactly what that request does, the three settings that move it, and why a fresh session still beats waiting for it.

Made with DispatchSEO

Auto-compact is Claude Code summarizing your conversation on its own once context nears the limit for your model, so the session can keep running instead of stopping cold. Mechanically it is a single extra request: the same system prompt, tools, and history you already have, plus a summarization instruction tacked on the end, which is why it reads your existing cache instead of reprocessing the whole conversation. Three settings can move when that request fires. None of them can make it wait longer than your model's own default.

TL;DR: Auto-compact fires automatically as context nears your model's compaction threshold, replacing your message history with a generated summary while CLAUDE.md and memory reload from disk. autoCompactEnabled (or DISABLE_AUTO_COMPACT=1) turns it off entirely; CLAUDE_AUTOCOMPACT_PCT_OVERRIDE and CLAUDE_CODE_AUTO_COMPACT_WINDOW can only move the trigger earlier, never later. If a single large file or tool output refills context immediately, Claude Code stops after a few attempts with a thrashing error instead of looping. Configuring any of this still leaves you reacting to a limit - a fresh session at a fixed point like the 50% rule beats waiting for auto-compact either way.

What auto-compact actually does when it fires

Most explanations of this stop at "it summarizes the conversation," which is true but skips the part that explains the rest of its behavior. Per Anthropic's current documentation, compaction sends a one-off request built from your exact conversation so far, with a summarization instruction appended as the final message. Because that request shares the same prefix as your normal turns, it reads from the cache instead of reprocessing your full history from scratch - most of the time a compaction takes goes to generating the summary, not to a cache miss.

Once that summary comes back, it replaces your message history outright. The system prompt was never part of that history to begin with, so it survives untouched. Project CLAUDE.md and auto memory get reloaded from disk on your next turn, which is why an edit you made to CLAUDE.md mid-session only takes effect after a compact (or a clear, or a restart) rather than immediately. What does not carry over cleanly is anything that lived only in the conversation itself: full file contents Claude had read, intermediate reasoning, and the specific back-and-forth that led to a decision, all compressed into whatever the summary chose to keep.

The three settings that control it - and the one thing none of them can do

Every setting Anthropic documents for auto-compact moves the trigger point. None of them can move it past your model's own default in the other direction.

That asymmetry is easy to miss if you only skim one setting in isolation. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90 reads like it should buy you more room before compaction kicks in. It does not - a value above the default for your model simply has no effect, per Anthropic's own documentation. The only lever that changes whether auto-compact runs at all is autoCompactEnabled (or its environment-variable equivalent, DISABLE_AUTO_COMPACT); the other two only ever tighten the leash.

What "context left until auto-compact" means when it hits 0

Claude Code's context readouts express this as a countdown to the threshold, not to some hard wall where the model stops functioning. A reading of 0% means the compaction threshold has been reached, or is about to be on the next turn - it is a signal that auto-compact is imminent or already running, not that Claude has run out of working memory entirely. Run /context at any point in a session for the live, categorized version of that same number, including what is actually filling the window right now rather than just how close you are to the trigger.

When auto-compact stops helping: the thrashing failure mode

Auto-compact assumes freeing space once is enough. Sometimes it is not. If a single file read or tool output is large enough to refill context back to the limit immediately after a summary, and that repeats a few times in a row, Claude Code stops retrying rather than keep burning API calls on a loop that is not making progress - you will see an error naming it a thrashing loop. That is a real, named failure mode in Anthropic's troubleshooting documentation, not a bug report you have to piece together from a forum thread.

Recovering from it is a scoping problem, not a settings problem: read the oversized file in smaller chunks (a specific line range or function instead of the whole thing), run /compact with an explicit focus that drops the large output, hand that piece of work to a subagent so it runs in its own separate context window, or run /clear if the earlier conversation is not worth keeping anyway.

Why a fresh session at 50% still beats configuring auto-compact

Every setting above changes when auto-compact reacts. None of them change what it fundamentally is: a reactive process that waits for you to approach a limit, then hands back a summary that dropped full file contents and intermediate reasoning to fit. Tuning the trigger earlier just means you hit that same tradeoff sooner.

ClockedCode's 50% context rule sidesteps the tradeoff instead of tuning it: once a session crosses roughly half its window, you write your own handoff file describing exactly what matters, and start clean. You choose what survives instead of trusting a model-generated summary to guess it, and the threshold does not depend on which model you happen to be running or a percentage buried in an environment variable. It costs one command more than doing nothing. For anyone who has been burned by a summary that quietly dropped the one decision that mattered, that trade is worth making before auto-compact ever gets the chance to fire.

When auto-compact is fine left alone

None of this means you need to touch these settings for every session. Short, single-task conversations that finish well before the threshold never trigger auto-compact at all, and a long exploratory chat where losing some early detail genuinely does not matter is exactly the case auto-compact was built for - configuring it or replacing it with a fresh session is only worth the effort once a session's context is doing real, hard-to-reconstruct work. If you are not sure which kind of session you are in, the deeper breakdown of what fills Claude Code's context window and the wider usage-limit checklist both cover the habits worth having before auto-compact becomes the thing saving you.

FAQ

What does Claude Code auto-compact actually do?

It sends one extra request once your context nears the compaction threshold: the same system prompt, tools, and history as your conversation, plus a summarization instruction appended at the end. That request reads your existing cache rather than reprocessing everything, and the generated summary then replaces your message history. CLAUDE.md and auto memory reload from disk on the next turn.

How do I control when Claude Code auto-compacts?

Three settings, each documented at code.claude.com. autoCompactEnabled in settings.json (or DISABLE_AUTO_COMPACT=1 as an environment variable) is the only full on/off switch, default true. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (1-100) moves the trigger percentage earlier. CLAUDE_CODE_AUTO_COMPACT_WINDOW shrinks the token budget that percentage is calculated against. None of the three can push the trigger later than your model's own default - only earlier.

What does "context left until auto-compact" mean when it reads 0?

It is a countdown to the compaction threshold, not to running out of memory entirely. At 0 the threshold has been reached (or is about to be), so Claude Code is compacting or is on the verge of it. The session does not end there; the next turn runs on the summarized history instead of the full one.

Why did auto-compact stop working and show a thrashing error?

Compaction succeeded, but a file or tool output refilled the context right back to the limit several times in a row, so Claude Code stopped retrying rather than burn API calls on a loop that was not making progress. Fix it by reading the oversized file in smaller chunks, running /compact with a focus that drops the large output, delegating that work to a subagent, or running /clear.

Is it better to configure auto-compact or just start a fresh session?

Configuring it only ever moves a reactive event earlier - it still waits for you to near the limit, then hands you a summary that drops full file contents and intermediate reasoning either way. A fresh session at a fixed point, like the 50% rule, is proactive and model-independent: you choose the moment and hand off a file you wrote yourself, instead of accepting whatever the auto-generated summary kept.