Introduction
If you've spent a long session in Claude Code, you've seen the indicator: "context left until auto-compact." It's a progress bar for the one resource every agentic coding session runs out of — the context window, the finite buffer that holds every prompt, response, file read, and tool output in the conversation. When that buffer fills, Claude Code compacts the history automatically so the session can keep going. Understanding what that does, and taking control of it, is one of the highest-leverage skills for working with an AI agent on real code.
This guide explains what the indicator means, what auto-compact actually does to your conversation, how to fix the "thrashing" error that can stall a session, and how to steer compaction so it keeps the parts of the context you care about.
What the indicator is telling you
The context window is a fixed-size buffer, like a notepad with a set page count. Every token — every message, every file you read, every command's output — takes up space on that notepad. "Context left until auto-compact" is simply how much of the notepad remains before Claude Code steps in to make room.
A healthy session hovers with comfortable headroom. When you watch that number fall quickly, it's usually because a tool returned a large output — a whole file, a long build log, a big search result — and consumed a chunk of the window in one shot. The indicator is your early warning that a summary is coming, and your cue to act before it does if you want control over what's kept.
What auto-compact actually does
When the conversation approaches the window's limit, auto-compact does three things: it analyzes the conversation to identify what's worth preserving, writes a concise summary of the earlier interactions and decisions, and replaces the older messages with that summary. The session continues with the summary standing in for the raw history.
The important caveat is that summarizing is lossy. Auto-compact preserves the gist, but fine-grained detail from early in the session — an exact error string, a specific line you looked at two hours ago — can be dropped. That's not a bug; it's the tradeoff that lets a long session continue at all. But it's the reason you sometimes want to compact on your terms rather than letting it happen automatically at the worst moment.
Take manual control with /compact
You don't have to wait for the automatic trigger. Run /compact yourself, and — more usefully — tell it what to keep:
/compact keep only the plan and the diff
The instruction after /compact steers the summary. If you're mid-refactor, "keep the plan, the files changed, and the failing test" preserves exactly what the next step needs and discards the exploration that got you there. Manual compaction at a natural checkpoint — after finishing a subtask, before starting the next — gives you a clean, intentional context instead of an automatic summary taken at a random point.
Fix the "auto-compact is thrashing" error
Sometimes you'll see:
Autocompact is thrashing: the context refilled to the limit...
This means compaction succeeded, but a file or tool output immediately refilled the window — several times in a row. Claude Code stops retrying rather than burn API calls on a loop that isn't making progress. The cause is almost always one oversized thing being pulled into context repeatedly. To recover, in rough order:
- Read the big file in chunks. Ask Claude to read a specific line range or a single function instead of the whole file. This is the most common fix — one enormous file is usually the culprit.
- Compact with a focus that drops the large output. For example,
/compact keep only the plan and the diffexplicitly excludes the giant log or file that's refilling the window. - Move the heavy work to a subagent. A subagent runs in its own separate context window, so the large-file work doesn't pollute your main session.
- Run
/clearif the earlier conversation is no longer needed at all.
Preserve the right things with CLAUDE.md
If you always want compaction to protect certain information, don't repeat the instruction every time — make it standing policy. You can customize compaction behavior directly in the CLAUDE.md file at the root of your project by adding a compact-instructions heading:
# Compact instructions
When you are using compact, please focus on test output and code changes
The summarizer applies this on every compaction, automatic or manual. And because CLAUDE.md is reloaded fresh at the start of each session — and after each compaction — it's the one place in your setup that never gets summarized away. This is where you encode project-specific priorities: keep the architecture decisions, keep the API contract, summarize the UI exploration briefly. It turns compaction from a lossy accident into a predictable behavior you've configured.
When to /clear instead of /compact
The two commands solve different problems, and using the wrong one wastes context:
/compactkeeps a condensed version of the conversation. Use it to continue the same task with less baggage./cleardiscards the conversation entirely and starts fresh. Use it when you switch to unrelated work.
Starting a genuinely new task in an old, compacted session means Claude carries a summary of irrelevant history that still costs tokens and can mislead it. When the new work has nothing to do with the old, /clear is the right, cheaper choice. You can always resume a previous session later with claude --resume in the same directory.
Reduce how often you hit the limit
A few habits keep you away from the ceiling in the first place. Use /compact regularly at natural checkpoints rather than waiting for the automatic trigger. Close and restart Claude Code between major, unrelated tasks. Add large build and dependency directories to your .gitignore so they don't get pulled into context during searches. To see where your context is actually going, run /context for a breakdown of what's consuming space and /usage to check token usage; /doctor also reports context usage as part of a broader health check. One quirk worth knowing: in a brand-new session, /compact prints Not enough messages to compact. because there's no history to summarize yet.
Conclusion
Auto-compact is what makes long agentic coding sessions possible, but left entirely on autopilot it summarizes at moments you didn't choose and drops detail you might have wanted. The fix is to treat context as something you manage, not something that happens to you: watch the indicator, compact manually at checkpoints with a focus instruction, encode your priorities in CLAUDE.md, and reach for /clear when the work truly changes. The thrashing error, when it appears, is almost always one oversized file — read it in pieces or hand it to a subagent, and the session recovers.
To go deeper on the underlying mechanics, see our glossary entries on the context window and the KV cache that stores attention state as the window fills.