autoCompactThreshold

What it does

autoCompactThreshold is a setting that automatically summarizes and compresses your conversation history when the session reaches a certain percentage of the context window. When this threshold is crossed, Claude Code silently runs a compaction pass: recent context remains available, older exchanges get summarized into a compact recap, and unused information gets pruned. This keeps your conversation running smoothly without you having to manually invoke /compact.

The default is typically 85%, meaning compaction kicks in when you've used 85% of the available context. At that point, the harness automatically summarizes what's happened so far, preserving critical facts while discarding verbose explanations, backtracking, and clarifications that are no longer load-bearing.

When to use it

Lowering autoCompactThreshold (to 75%, for example) makes sense if you're working on a long, exploratory task where context churn is constant—say, deep code investigation across a large codebase, or a multi-file refactor with many back-and-forth decisions. Compacting earlier leaves more headroom and prevents you from unexpectedly hitting the wall mid-conversation.

Raising it (to 90%+) works if you're doing short, focused tasks that rarely approach the context limit. You keep more raw history visible for longer, which can be helpful if you need to reference exact phrasing from an earlier exchange.

The trade-off: lower threshold = more compact summaries, less raw history visible when reviewing; higher threshold = more verbosity preserved, but you risk running out of room mid-thought. Neither is a perfect answer—tune it to match how you work.

Try it yourself

Check your ~/.claude/settings.json file and look for autoCompactThreshold. If it's not there, the default (85%) is in effect. Open a long, multi-topic conversation with Claude Code—something with at least 10–15 exchanges—and watch the context window indicator in the UI. When you cross the threshold, a compaction happens automatically. Now try lowering the threshold to 70% and repeat a similar conversation; you'll see compaction kick in earlier and more aggressively.

Gotchas

Setting autoCompactThreshold too low (say, 60%) will cause frequent, aggressive compactions that lose nuance fast. You might ask about a decision made 20 messages ago and get a vague summary instead of the specifics that led to it.

Conversely, setting it too high (95%+) defeats the purpose—you're basically relying on manual /compact to save you, and you might run out of context before the automatic trigger fires.

Remember: autoCompactThreshold is automatic and silent. The manual /compact command is explicit and immediate—useful when you know you're about to start a completely new topic and want to start fresh right now without waiting for the threshold. They're not competing; autoCompactThreshold is a safety net; /compact is a deliberate floor sweep when you sense context bloat.