Claude Code Auto Compact: How It Works and How to Control It

That trade is usually worth it — but it is a trade. Understanding claude code auto compact is the difference between a session that quietly gets dumber over three hours and one that stays sharp. This guide covers what compaction actually preserves, how to read the warning before it fires, the manual levers (/compact, /context, /clear), the documented setting to turn it off, and the habits that make compaction a non-event.

What claude code auto compact actually does

Every session has a context window: the system prompt, your CLAUDE.md, auto memory, loaded skill bodies, every file Claude read, every command it ran, and the whole back-and-forth. If you want the full picture of what fills that budget, our breakdown of the Claude context window walks through it piece by piece.

When that window fills, Anthropic's docs describe a two-stage response: Claude Code clears older tool outputs first, then summarizes the conversation if that isn't enough. Your requests and key code snippets survive. Detailed instructions from early in the conversation may not.

The important mental model: claude code auto compact does not delete anything on disk. Your files, your git history, and the session transcript under ~/.claude/projects/ are untouched. What shrinks is only what the model can see on the next turn.

What survives is documented precisely, and it's more nuanced than "everything is lost":

• System prompt and output style — unchanged, because they live outside the message history.
• Project-root CLAUDE.md, unscoped rules, and auto memory — re-injected from disk after every compaction.
• Rules with paths: frontmatter and nested CLAUDE.md files — lost until Claude reads a matching file again.
• Invoked skill bodies — re-injected, but capped at 5,000 tokens per skill and 25,000 tokens total, with the oldest dropped first.

That table is the single most useful fact about compaction, and it drives most of the strategy later in this article: anything that must survive claude code auto compact belongs in a file that gets re-injected, not in a message you typed an hour ago.

Reading the context indicator before compaction fires

You don't have to be surprised. Claude Code warns you as context tightens, and the CLI shows a "context left until auto-compact" style hint as you approach the limit. The moment it appears is your cue to act deliberately rather than let the automatic pass guess.

For a live breakdown, run /context. It renders your context usage as a colored grid, with per-category numbers and optimization suggestions for context-heavy tools, memory bloat, and capacity warnings. Pass /context all to expand the per-item list. /usage shows token and cost stats for the session — our guide on how to check token usage in Claude Code goes deeper on reading those numbers.

If you'd rather see it constantly, the status line exposes context_window.used_percentage and context_window.remaining_percentage as pre-calculated fields you can render as a progress bar. Note the fine print: used_percentage is computed from input tokens only, and both fields may be null early in a session before the first API response lands.

There's also a failure mode worth knowing. If one file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows a thrashing error rather than looping forever. That's a signal to /clear and change your approach — not to retry.

Manual control: /compact, /context, and /clear

The best use of claude code auto compact is to rarely let it run unattended. Compact on your own terms, at a natural boundary, with instructions about what matters.

/compact frees context by summarizing the conversation so far, and it accepts focus instructions. For example, /compact focus on the failing test and the API contract tells the summarizer what to keep — instead of letting the automatic pass decide on its own. Run it before a long new task, not in the middle of a delicate one.

Here are the levers, side by side:

/clear deserves a note, because people fear it. It starts a fresh conversation with an empty context; it does not delete your previous session. You can pass a name (/clear auth-refactor) to label the old conversation in the /resume picker, and /reset and /new are aliases. If you want to free context while continuing the same thread, that's /compact, not /clear. Our guide to Claude Code sessions covers resuming, forking, and the picker in detail.

Turning claude code auto compact off

It is a real, documented setting. In settings.json:

{
  "autoCompactEnabled": false
}

The default is true. It appears in /config as Auto-compact, so you can toggle it interactively mid-session. There's also an environment variable, DISABLE_AUTO_COMPACT, which you can set in the env block of your settings.

Should you? For most people, no. With claude code auto compact disabled you don't get more context — you just lose the graceful fallback and hit the wall instead. Turning it off makes sense in narrow cases: scripted or CI runs where a silent summarization would corrupt a deterministic pipeline, or workflows where you'd rather stop and /clear than continue on a lossy summary. Otherwise, leave it on and control it with /compact.

If the real problem is that your window is too small, a bigger window is an option before disabling anything. Fable 5, Sonnet 5, Opus 4.6 and later, and Sonnet 4.6 support a 1 million token context window; Sonnet 5 currently runs at 1M with no [1m] variant to select, and the newest flagship models such as Claude Opus 4.8 handle long sessions well within the standard limit. Compaction works the same way at the larger limit — it just fires later.

Why compaction quietly degrades quality

Here's the part nobody tells you. A compact is not neutral. A summary of 150,000 tokens of work is a lossy compression, and what gets lost is exactly the kind of thing that matters: the constraint you mentioned once ("never touch the legacy adapter"), the exact error string from an hour ago, the reason you rejected the first approach.

The symptom is subtle. Claude doesn't announce that it forgot. It just starts re-suggesting an approach you already ruled out, or re-reads a file it already understood, or reintroduces a bug you fixed. This is the same drift that shows up in long chat threads — see our piece on the Claude conversation length limit for the consumer-app version of the problem.

The fix is architectural, not clever prompting:

1. Keep sessions task-scoped. One session, one job. A session that fixes a bug, then refactors a module, then writes docs will compact — and the summary will be a blurry average of three unrelated things.
2. /clear between unrelated tasks. It's free, it's instant, and stale context costs tokens on every single subsequent message — the same bloat that makes Claude Code slow to respond as a session drags on. This is the highest-leverage habit on the list.
3. Put durable rules in CLAUDE.md. Project-root CLAUDE.md is re-injected from disk after every compaction, so rules there survive by design. Keep it under about 200 lines and move long procedures into skills, which load on demand.
4. Delegate fan-out to subagents. A subagent gets its own fresh context window; only its summary returns to your main thread. Sending a big research or log-parsing job to a Claude Code subagent is the cleanest way to keep the main conversation lean.
5. Re-state key constraints after a compact. When you see "Conversation compacted," spend one line restating the goal and the hard constraints. Thirty seconds of typing beats twenty minutes of wrong direction.

None of this is exotic. It's the same discipline that makes any long agent session work, and it's covered from other angles in our Claude Code tips and tricks. Adopt the habits early and your sessions stay sharp long past the point where they'd otherwise start drifting.

Auto-compact is only one lever — Claude Code context management puts it alongside /context, /clear, /compact, and subagents so you act around 60% instead of waiting for the automatic pass.

The short version

Claude code auto compact is a good default doing an unglamorous job: keeping your session alive when the context window fills. Treat it as a backstop, not a strategy. Watch /context, compact deliberately with focus instructions, /clear between unrelated tasks, keep your durable rules in CLAUDE.md where they get re-injected, and push heavy reads into subagents. Do that and claude code auto compact becomes a footnote instead of the reason your afternoon session went sideways.

Anthropic documents the mechanics in Explore the context window, and the token-reduction habits in Manage costs effectively.