Claude Code Context Window: What Happens When You Hit the Limit (and How to Fix It)

Your Claude Code Session Has a Memory — and It's Not Infinite

If you have spent serious time with Claude Code, you have probably run into a moment where Claude seems to forget something it knew thirty minutes ago — a decision you made about the database schema, a refactor you agreed on, an edge case you already handled. This is not Claude being careless. It is a direct consequence of how large language models work: they can only "see" a finite amount of text at once.

That finite window is called the context window, and understanding it will save you hours of frustration on long coding sessions.

What the Context Window Actually Is

Every time Claude Code responds to you, it processes a single block of text that contains everything relevant to that moment: your current message, every message before it in the session, every file Claude has read, every bash command output, every tool result. The model cannot reach outside that block. If something falls outside it, the model cannot see it.

That block has a maximum size measured in tokens. A token is roughly three to four characters of English text — not quite a word, not quite a character. A 500-line TypeScript file might be around 1,500–2,000 tokens. A full page of conversation might be 300–600 tokens.

Claude Sonnet 4.6 and Claude Opus 4.7 both have a 1 million token context window. That sounds enormous, and it is. But long coding sessions fill it faster than you expect because the window accumulates everything:

• Every message you have typed
• Every reply Claude has given
• The full content of every file Claude has read during the session
• Complete bash outputs — including those 500-line build logs you piped in
• All tool call inputs and results

Run a two-hour session that reads a dozen files, runs builds, and goes through several rounds of refactoring, and you can realistically consume 100,000–300,000 tokens. For very large codebases or very long sessions, even 1 million tokens can become a real constraint.

Signs You Are Approaching the Limit

You don't always get a hard error. The degradation often looks like this:

• Claude forgets earlier decisions. You already settled on using Zod for validation two hours ago, and now Claude is suggesting you add a different library.
• Responses become contradictory. Claude says to use one approach, then later recommends the opposite.
• Accuracy drops on details. Claude starts hallucinating function signatures or file names you discussed earlier.
• A context warning appears in the terminal. Claude Code shows a notice about the context being nearly full.
• Automatic compaction triggers. You see [Context compacted] in your terminal — Claude Code handled it for you, but it's a signal you've been in a long session.

What Happens Automatically: Compaction

When Claude Code detects that the context is approaching its limit, it doesn't just crash or start refusing requests. It automatically compacts the conversation.

Here is what that looks like in practice:

1. Claude Code pauses briefly before responding.
2. It summarizes the earlier portion of the conversation — capturing the key decisions, file paths discussed, patterns established, and conclusions reached.
3. The raw earlier messages are replaced by this condensed summary.
4. You see [Context compacted] in the terminal.
5. The session continues as normal.

The summary preserves the essential facts: architectural decisions, code patterns you agreed on, which files matter, what bugs you fixed. What it loses is the verbatim back-and-forth — the exact wording, exploratory tangents, and step-by-step reasoning that has already served its purpose.

Automatic compaction works well for most sessions. But sometimes you want more control — either to compact at a natural stopping point, or to start completely fresh.

Manual Controls: Taking Back Control of Your Context

/clear — Wipe the Slate

The /clear command deletes the entire conversation history. Zero context. Fresh start.

Use it when:

• You are switching from one task to a completely unrelated one
• You want to start a new feature with no baggage from a previous debugging session
• You have already committed or merged the work and you are moving on

The trade-off is obvious: you lose everything Claude knew about what you were just doing. That is exactly what you want when switching tasks. For the same task, it is usually too aggressive.

/compact — Summarize Now, On Your Terms

The /compact command manually triggers compaction before Claude Code forces it. You control when the compression happens, which means you can pick a natural checkpoint — after a refactor is done, after a bug is fixed, before starting a new module.

Type it plain:

/compact

Or give Claude a hint about what matters most:

/compact focus on the auth refactor decisions and the database schema changes

When you include a focus hint, Claude prioritizes keeping that information intact in the summary. Everything else gets compressed more aggressively.

Starting a New Session with --continue

If you use /clear and then want to pick up where you left off with session metadata preserved (working directory, tool permissions, etc.), you can start a new session with the -c or --continue flag. This gives you a fresh context while inheriting your session configuration.

--fork-session — Branch Your Session

The --fork-session option creates a copy of your current session. Both branches start with the same history, and then diverge independently from that point.

This is powerful when you want to explore two different approaches to a problem without contaminating one with the other. Keep the original session for context-heavy work (like a big refactor), and run the fork for quick isolated experiments.

Strategies to Stay Well Within the Limit

The best context management is preventative. These habits will keep you from hitting the wall in the first place:

1. Use /clear between unrelated tasks If you just finished fixing a bug and you are about to start a new feature, clear the context. The two tasks share no useful history.

2. Let Claude read files with the Read tool instead of pasting them When you paste a file's contents directly into the chat, every token of that file is embedded in the conversation history permanently. When Claude reads a file using the Read tool, the content is fetched and used — but the file isn't necessarily re-embedded in the same way. More importantly, Claude can re-read it fresh on demand without it taking up permanent space in your chat history.

3. Use .claudeignore to prevent auto-reading huge generated directories Create a .claudeignore file in your project root using the same syntax as .gitignore. Add entries like:

node_modules/
.next/
dist/
build/
coverage/
*.lock

This prevents Claude from accidentally reading machine-generated files that contribute thousands of tokens with zero value.

4. Keep bash output concise Long bash outputs are context killers. Instead of running a command and showing the full output, pipe it through head, grep, or tail:

# Instead of showing 2000 lines of test output
npm test 2>&1 | grep -E "(PASS|FAIL|Error)" | head -50

Claude gets the signal it needs without thousands of tokens of noise.

5. Break large refactors into focused sessions per module Instead of one 4-hour session refactoring your entire backend, do one session per module. Each session stays focused, context stays clean, and you get natural checkpoints to review and commit work.

Understanding Token Usage: A Quick Reference

To build intuition for how fast context fills up:

The numbers add up quickly. A session that reads 5 files, produces 3 build outputs, and goes through 20 rounds of conversation can consume 30,000–60,000 tokens before you know it.

CLAUDE.md vs Session Context: Know the Difference

One of the most important things to understand about Claude Code's memory model is that CLAUDE.md is not the same as session context.

Session context is the live conversation window — everything since you started this session. It grows as you work and gets compacted or cleared.

CLAUDE.md is a file in your project root (or ~/.claude/CLAUDE.md for global settings). Claude Code reads it at the start of every session, fresh. It doesn't accumulate over time. It doesn't get compacted. Whatever is in that file is always available at the start of any session.

This means you should use CLAUDE.md for:

• Project architecture and patterns
• Coding standards your team follows
• Key file locations and module responsibilities
• Technology decisions that are stable over time
• Instructions Claude should always follow in this project

By putting stable information in CLAUDE.md instead of re-explaining it in chat, you avoid burning context on information Claude could just read from a file. You also ensure Claude has that context from the very first message, not after you've already used up tokens explaining it.

Putting It All Together

Managing Claude Code's context window is less about fighting a limitation and more about developing good workflow habits. The model is powerful precisely because it can hold a large amount of context — the goal is to make sure that context is the right context.

Keep your sessions focused. Use /compact at natural checkpoints. Use /clear when switching tasks. Let .claudeignore protect you from unnecessary bulk. Put stable project knowledge in CLAUDE.md where it belongs.

When you build these habits, you stop thinking about the context window as a constraint and start using it as a tool — a precision buffer that holds exactly what you need for the work in front of you.