What Happens When Claude Code Runs Out of Context

Nothing dramatic. Claude Code does not crash, and it does not lose your files. When the conversation approaches the model's context limit, it compacts: it writes a summary of the session so far, discards the raw history, and continues with that summary plus the most recent turns. The session keeps going.

What you lose is fidelity. The summary is a compressed retelling, and compression is lossy in a specific, predictable direction. It keeps the narrative ("we are refactoring the auth module, tests are passing") and drops the particulars (the exact stack trace, the file it read once at line 400, the approach you vetoed an hour ago and why). Most of the frustration people report after a long session is not the model getting dumber. It is the model working from a summary of a summary while you are still working from your own memory of the full conversation.

Here is what is actually happening, what it costs you, and how to work so it stops mattering.

What is actually in the context window

The window is not just your chat. On every turn, the model sees roughly:

• The system prompt and the full schema for every available tool (including MCP servers, which can be surprisingly large)
• Your CLAUDE.md files and any other loaded instructions
• The conversation itself, your messages and its replies
• Every tool result: file contents it read, grep output, bash stdout, test runs, diffs

That last category is almost always the largest and the least valuable per token. A single npm test failure can cost more of the window than an hour of your instructions. Reading a 2,000 line file to change three lines leaves all 2,000 lines sitting in context for the rest of the session.

You can see the breakdown yourself. /context shows where the tokens are going. It is worth running once mid-session on a real project, because the split is rarely what people assume.

The sequence as the window fills

Claude Code warns you as you get close, then auto-compacts when it has to. Auto-compaction is a normal part of the loop, not an error state. Newer versions also prune stale tool results before resorting to a full compaction, which buys real headroom, since old file reads are exactly the thing you least need to keep verbatim.

You have three levers of your own:

• /compact compacts on demand, and it accepts instructions. /compact focus on the caching bug and the decisions we made about invalidation produces a far better summary than the automatic one, because you are telling it what matters.
• /clear wipes the context entirely and starts fresh in the same directory. This is not a lesser version of compacting. It is a different tool.
• claude --continue and claude --resume bring a previous session back, which means "I ran out of context" never has to mean "I have to explain the project again from scratch."

The important distinction: compaction preserves a lossy thread of the whole session. Clearing preserves nothing but your project files and CLAUDE.md. Sometimes nothing is the better starting point.

The failure modes you will actually notice

Amnesia loops. The model re-reads a file it already read, re-derives a decision you already made, or reintroduces a bug it fixed forty minutes ago. This is the classic post-compaction symptom, and it is expensive: the re-reading burns the context you just freed.

Instruction drift. Rules you gave in chat ("use the existing logger, do not add a new dependency") are exactly the kind of detail a summary drops. Rules in CLAUDE.md are re-injected on every turn and survive compaction intact. This asymmetry is the single most useful thing to internalize.

Confident staleness. After compaction the model will describe the plan fluently. Fluency is not evidence that the details survived. Verify before you let it act on a plan it is restating rather than rereading.

Cost and latency. A near-full window means every single turn resends a large prompt. Long sessions get slower and pricier at exactly the point where they are also getting less accurate.

How to work so it stops being a problem

Treat the filesystem as the real memory. Chat is a scratchpad that gets erased. Files do not. Durable rules go in CLAUDE.md. The current task goes in a plan file that the model reads and updates as it works: what we are doing, what is done, what was tried and rejected and why. After a compaction, that file is the recovery point. This one habit removes most of the pain.

Commit early and in small pieces. git log and git diff are memory the model can query cheaply. A session that has committed six times is far easier to recover than one carrying six hours of uncommitted work in its head.

Compact at a seam, not at a cliff. The worst time to compact is mid-refactor when the model is holding a mental model of half-finished edits. The best time is right after a commit, when the state of the world is written down anyway. Run /compact with instructions at the seam, before auto-compaction picks the moment for you.

Clear more often than feels natural. One task, one session. When you finish the bug and move to the unrelated feature, /clear. Carrying the bug's context into the feature does not help the feature and actively crowds it out.

Point, do not paste. Give file paths and let it read what it needs. Pasting a whole file guarantees the whole file lives in context permanently; letting the model read targeted ranges does not.

Push exploration into subagents. A subagent gets its own context window and returns a conclusion, not the fifty file reads it took to get there. "Find every place we construct this client" is a perfect subagent task: the searching is expensive, the answer is three lines. Your main session pays for the answer only.

Be deliberate about MCP servers. Every connected server contributes tool schemas to every turn. Servers you are not using in this session are pure overhead.

The workflow that holds up

Start a session with a clear goal and a plan file. Let it work. Commit at each meaningful checkpoint and update the plan file. When the context warning appears, finish the current step, commit, then /compact with a one line instruction about what to preserve. When the task is genuinely done, /clear and start the next one clean.

That is not a workaround for a limitation. It is roughly how a careful engineer hands work to a colleague, and it happens to be exactly what a context-bounded agent needs.

FAQ

Does running out of context lose my work? No. Files on disk, edits already applied, and commits are all untouched. Only the conversation history is compressed.

Is compacting the same as clearing? No. Compaction replaces the history with a summary and continues the same session. Clearing discards the history and starts fresh. Compact when continuity matters, clear when you are changing tasks.

Can I turn off auto-compaction? It is configurable. Turning it off does not give you more context, it just means you manage the boundary manually instead of having it managed for you. Most people are better served by leaving it on and compacting deliberately before it triggers.

Would a larger context window solve this? It raises the ceiling, and that genuinely helps. It does not remove the problem. Large contexts still cost more per turn, still get slower, and recall across a very long context is not uniform. Good session hygiene pays off at every window size.

How do I know how much room is left? Run /context. It shows the current usage and where it is going, which is usually more actionable than the number itself.

The honest summary: Claude Code running out of context is a managed event, not a failure. Your job is to make sure the things that matter live somewhere the compaction cannot reach.