The "context window exceeded" error in Claude Code means the session hit the token limit and stopped. The fix: use /compact to compress history, .claudeignore to block unnecessary files, and split long tasks across sessions. Prevention is better than recovery—monitor usage with /cost and act before it fills up.
You hand a large refactor to Claude Code, walk away, and come back to find "context window exceeded." Work stopped. No idea how far it got. The files are in a half-finished state, and you don't have the context in your head to pick up where it left off. If this sounds familiar, you're not alone—it's one of the most common complaints in developer communities.
This article covers everything you need: a complete playbook for preventing context window errors and recovering cleanly when they do happen.
What Is the "Context Window Exceeded" Error in Claude Code?
The "context window exceeded" error means Claude Code has hit the upper limit of tokens it can process in one session. Everything counts toward that limit: the full conversation history, every file it has read, all the code it has generated.
As of March 2026, Claude Code supports a 200K token context window for most models, and a 1M token context window for Opus 4.6 and Sonnet 4.6. That sounds enormous—but large codebases and long conversations eat through it faster than you'd expect.
The critical insight is that this limit doesn't arrive suddenly—it approaches gradually. Claude Code tracks context usage throughout a session, and there are ways to monitor it. That means you can act before the error ever appears.
There are four main strategies:
- Use
/compactto summarize and compress conversation history - Use
.claudeignoreto prevent unnecessary files from being read in the first place - Split long sessions by domain so they never get out of hand
- Use Plan mode to lock in design decisions upfront, minimizing token spend during implementation
I'll cover each in detail. But first—what to do when the error has already happened.
How Do You Recover Your Work After a Context Window Error?
When the error hits, the session is over. Don't panic. Follow these steps to understand the situation.
Step 1: Check the diff with git
git diff HEAD
git status
Claude Code writes changes to disk as it goes. Even if the session ended abruptly, everything it touched is still there in the file system. Running git diff tells you exactly what changed and how far the work progressed.
Step 2: Save the current state
Even if the state looks incomplete, save it immediately.
git add -A
git stash push -m "claude-code session interrupted - context exceeded"
Or commit the parts that look complete. Either way, secure the work before doing anything else.
Step 3: Start a new session with minimal context
Open a new session and describe what's needed in compact form.
The previous session ended with context window exceeded.
Modified files: src/components/Header.tsx, src/lib/api.ts
Remaining task: fix type errors in the Footer component
Please load only the relevant files and continue.
No long explanations needed. "What to do" and "which files" are all that matter. The worst thing you can do is paste the entire previous conversation into the new session—that defeats the purpose.
How Do You Monitor Context Usage in Claude Code?
Prevention starts with visibility. If you don't know how close you are to the limit, you can't act in time.
Use /cost to check token consumption
/cost
The /cost slash command shows cumulative token usage for the current session. If you're doing a feature that involves many files, check it every 20–30 minutes.
Watch for the auto-compact trigger
Claude Code auto-compacts when context usage reaches approximately 80–85% of the window. If you see an auto-compaction message, that's your late warning. You're deep into the window and should consider wrapping up the current task.
Rough guidelines for session "weight"
| Situation | Approximate token usage |
|---|---|
| Small bug fix (1–2 files) | 10–30k |
| Feature addition (5–10 files) | 50–150k |
| Large refactor (20+ files) | 200k+ — danger zone |
Token usage scales faster than you'd expect as file count grows. Every "while you're at it, fix this too" request accelerates you toward the limit.
The right mindset for context efficiency
- One session = one task, no exceptions
- No "while you're at it" requests
- New tasks always start in new sessions
How Does /compact Work and When Should You Use It?
The /compact command summarizes your conversation history and replaces it with a compressed version. The detailed back-and-forth becomes a concise summary of what's been accomplished. Token count drops significantly, and you can continue working.
/compact
You can also pass a focus topic to guide the summary:
/compact focus on the authentication refactor decisions
This tells Claude what to prioritize when compressing. Useful when only part of the conversation is still relevant.
Good times to use /compact
- When context usage reaches 60–70%
- When transitioning from a research/design phase to implementation
- When a debugging session has reached a natural stopping point
When to avoid it
- In the middle of a complex design discussion (the summary may lose important nuances)
- When precise code details need to be preserved
/compact isn't perfect. Important decisions can get lost in summarization. The safest habit is to write key decisions to a file—or to CLAUDE.md—before compacting.
## Current Work
- Task: refactor user authentication module
- Decision: switch from JWT to session cookies
- Modified: src/auth/index.ts, src/middleware/auth.ts
- Remaining: update tests
Record decisions in CLAUDE.md before running /compact. If a decision only lives in the conversation, it can be summarized away. If it's in a file, Claude Code can always re-read it.
How Do You Reduce Token Usage with .claudeignore?
The single most effective context management technique is preventing unnecessary files from being loaded in the first place. The .claudeignore file works like .gitignore—it tells Claude Code which files and directories to skip when exploring the project.
touch .claudeignore
# .claudeignore
# Dependencies (never load these)
node_modules/
vendor/
.venv/
__pycache__/
# Build artifacts
dist/
build/
.next/
out/
# Large data files
*.csv
*.json.bak
data/raw/
# Logs and caches
*.log
.cache/
coverage/
# Archive docs not needed for current work
docs/archive/
*.pdf
# Test snapshots
__snapshots__/
The impact is real
On a mid-size Next.js project, adding a .claudeignore that excludes node_modules/, .next/, and build artifacts makes sessions last dramatically longer before hitting the limit. Excluding node_modules/ alone can save tens of thousands—sometimes hundreds of thousands—of tokens per session.
How Should You Split Sessions to Handle Long-Running Tasks?
The most fundamental solution to context management is splitting one large task into multiple focused sessions.
What splitting looks like
Bad (one session tries to do everything):
- Design the user auth system
- Design the DB schema
- Implement the API
- Build the frontend
- Write tests
- Configure deployment
Good (separate sessions):
Session 1: Design only (record decisions in CLAUDE.md)
Session 2: DB + API
Session 3: Frontend
Session 4: Tests
Session 5: Deployment config
The biggest cause of context explosion is trying to carry the full history of a previous session into a new one. Each session should start fresh, with only the minimum context needed.
Create a handover file between sessions
<!-- session-handover.md -->
## What was completed last session
- Auth implemented using JWT (RSA256)
- Files under src/auth/ are complete
- Tests not written yet
## What to do this session
- Add tests under src/auth/__tests__/
- Target: 80%+ code coverage
Hand this to Claude Code at the start of each session. The long explanatory conversation becomes unnecessary.
Use CLAUDE.md as persistent memory
Unlike conversation history, CLAUDE.md survives across sessions. Architecture decisions, naming conventions, project-specific rules—put them in CLAUDE.md once and every session has access. This is far more token-efficient than re-explaining context each time. See CLAUDE.md Design Patterns for Context Management for practical patterns.
How Does Auto-Compaction Work and When Should You Disable It?
Claude Code has an auto-compaction feature that automatically summarizes context when usage crosses approximately 80–85% of the window. It sounds convenient, but auto-compaction during critical work can cause problems.
You can control the auto-compaction threshold with an environment variable:
# Lower the threshold to trigger compaction earlier (at 70%)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70
Or disable it entirely via the CLI settings:
claude config set -g autoCompactEnabled false
Disabling auto-compaction and running /compact manually is the safer approach for complex work. Check the summary before continuing. Make sure nothing critical was lost.
For routine tasks (simple bug fixes, small features), leaving auto-compaction on is fine—it handles context silently and you never notice. The risk is only with work that depends on precise context continuity.
What's the Setup Checklist for Preventing Context Window Errors?
Here's everything from this article as an actionable checklist. Set this up once per project and you'll rarely have to think about it again.
Project initialization
- Create
.claudeignore, excludingnode_modules/,dist/,.next/ - Create
CLAUDE.mdand establish the habit of recording decisions there - Set auto-compaction threshold or disable it for complex projects
At the start of each session
- One task per session—no mixing
- Pass only the minimum necessary context from the previous session
- Never ask Claude Code to load files unrelated to the current task
During a session
- Run
/costperiodically to monitor token usage - Run
/compactwhen usage hits 60–70% - Refuse the temptation to add "while you're at it" requests
- Write design decisions to a file immediately—don't leave them only in the conversation
When the error happens
- Run
git diffto see what changed - Stash or commit the current state
- Start a new session with a compact, focused handover message
Frequently Asked Questions
How big is Claude Code's context window?
As of March 2026, Claude Code supports 200K tokens for most models and 1M tokens for Opus 4.6 and Sonnet 4.6. Auto-compaction reserves a buffer (roughly 33K tokens on 200K windows), so your effective working limit is lower than the headline number.
Does /compact delete my conversation history?
Not exactly. /compact replaces the detailed conversation with a compressed summary. The original messages are gone from context, but the key information is preserved in summary form. You can still continue working—Claude picks up where you left off based on the summary.
Is .claudeignore the same as .gitignore?
They use the same syntax, but serve different purposes. .gitignore controls what Git tracks. .claudeignore controls what Claude Code can see and read. Many entries overlap (like node_modules/), but .claudeignore lets you exclude files that Git does track but Claude doesn't need—like large test fixtures, docs archives, or data files.
Can I increase the context window size?
You can't increase the hard limit—it's set by the model. But you can use Claude Code with Opus 4.6 or Sonnet 4.6 to get 1M tokens instead of 200K. On Max, Team, or Enterprise plans, the 1M window is available automatically.
What's the difference between /compact and starting a new session?
/compact preserves the working context in summary form within the same session. A new session starts completely fresh—no history at all. Use /compact when you want to continue the same task with less overhead. Use a new session when you're switching to a different task entirely.
Does Plan mode help with context usage?
Yes. Plan mode lets you design the implementation before writing code. The design conversation uses tokens, but it produces a clear plan that makes the implementation phase faster and more focused—often using fewer tokens total than an unplanned coding session.
How do I recover files if Claude Code crashed mid-edit?
Claude Code writes to disk as it works. Run git diff HEAD and git status to see exactly what was changed. Then stash or commit the changes before starting a new session. Nothing is lost—it's all on disk.
Why does my session run out of context faster than expected?
Common causes: reading many files (especially large ones), long back-and-forth debugging conversations, and "while you're at it" scope creep. Each file read adds its full contents to the context. Use .claudeignore and keep sessions focused on a single task.
Wrapping Up
"Context window exceeded" is not bad luck. It's an engineering problem with engineering solutions.
- Use
.claudeignoreto control what gets loaded - Enforce one session, one task
- Run
/compactmanually at the 70% mark - Manage handoffs between sessions with files, not conversation history
- Record decisions in CLAUDE.md so they survive compaction
These practices eliminate almost all context-related interruptions. Even large-scale refactors become manageable when sessions are properly scoped.
Start right now: create a .claudeignore file in your project.
Related articles: