Claude Code 'Context Window Full' — What to Do When You Run Out of Space

The Problem

You're in the middle of a productive Claude Code session when you notice:

- The context indicator shows 85%+ usage - Responses start coming slower - Claude starts "forgetting" what you discussed earlier - You get the dreaded: "This conversation is too long. Please start a new one."

This is the context window full problem. Every Claude Code session has a limited "working memory" — once it's full, performance degrades.

This guide covers what to do right now when you hit the limit, plus how to prevent it from happening again.

---

Quick Fix: Start a New Session (30 Seconds)

This is the fastest way to recover:

# 1. Save your current state
/save context-save-1
# 2. Exit the session
/exit
# 3. Start a fresh session
claude
# 4. Reference what you need
@.claude/context-save-1.md Continue where we left off

> 💡 Pro tip: The /save command saves your conversation to a file. It's always available in Claude Code — use it before starting a new session.

If your version doesn't have /save, create a manual checkpoint:

cat > .claude/checkpoint.md << 'EOF'
Current Task
Building auth system
Completed
- Login form component
- API route: POST /api/auth/login
- JWT token generation
Files Created
- src/components/LoginForm.tsx
- src/app/api/auth/login/route.ts
Next Steps
- Password reset flow
- Rate limiting
Decisions
- Using JWT with httpOnly cookies
- Token expiry: 24h
EOF

---

Immediate Relief: Free Up Context Space

If you can't start a new session yet, try these to free up space:

1. Stop Discussing Completed Code

If Claude showed you code that's already written and working, don't keep discussing it. Say:

> Done with that. Let's move to [next task].

This tells Claude it can deprioritize the earlier discussion.

2. Use @ File References Instead of Context

Instead of keeping file contents in conversation memory:

// ❌ Wastes context:
Here's my current LoginForm.tsx:
[200 lines of code]
// ✅ Saves context:
@src/components/LoginForm.tsx — Add error handling to this

3. Clear the Terminal Output (If UI Shows Past Messages)

# In the Claude Code terminal UI:
clear

This only clears the visible display — context is retained, but the mental overhead is reduced.

4. Ask Claude to Summarize

> Summarize what we've done so far in 3 bullet points

This compresses your conversation into a much smaller representation, and Claude can then de-prioritize earlier messages.

---

Prevention Strategy 1: Use CLAUDE.md for Persistent Context

The single best prevention strategy. Any context in CLAUDE.md is available in every session without using conversation tokens:

# .claude/CLAUDE.md
Project
E-commerce app with Next.js + Prisma + Stripe
Architecture
- App Router in src/app/
- Shared components in src/components/
- Database: Prisma with PostgreSQL
- Payments: Stripe Checkout
Conventions
- Named exports for components
- TypeScript strict mode
- Never use any
- Error boundaries for all routes

External Links: - CLAUDE.md Documentation — official reference - Claude Code Memory Systems Explained — learn how memory works

---

Prevention Strategy 2: One Session Per Feature

Instead of one long session, use multiple focused sessions:

# Session 1: Design the auth system
claude
> Design the auth system architecture
> Create the user model
# /exit
# Session 2: Implement login
claude
> @.claude/CLAUDE.md @prisma/schema.prisma — Implement the login API route
# /exit
# Session 3: Implement signup
claude
> @.claude/CLAUDE.md @src/app/api/auth/login/route.ts — Implement signup
# /exit

Each session has a full 200K context window for its focused task.

---

Prevention Strategy 3: Use Decision Logs

When you have multi-session tasks, write decisions to a file:

# After a key decision in session 1:
> Write our decision about JWT vs session auth to docs/decisions/auth-strategy.md

Then in session 2:

> @docs/decisions/auth-strategy.md — Implement the auth system based on this design

The decision file takes far less context than re-explaining the entire discussion.

---

Prevention Strategy 4: The 50-Message Limit Rule

As a rule of thumb, start a new session after ~50 messages. At this point, your context window is typically 60-80% full.

Track your message count:

> How many messages have we exchanged?

Or just watch the context bar. When it hits 60%, it's time to plan the next session.

---

Prevention Strategy 5: Use Hooks for Auto-Saving

Automatically save session state at regular intervals:

// .claude/settings.json
{
  "hooks": {
    "postMessage": "./scripts/save-checkpoint.sh"
  }
}

With a save script:

#!/bin/bash
# scripts/save-checkpoint.sh
cp .claude/session-log.md ".claude/checkpoints/$(date +%Y%m%d-%H%M%S).md"

External Links: - Claude Code Hooks Automation Guide — more hook recipes - Claude Code Hooks Reference

---

Prevention Strategy 6: Smart Prompting

Reduce unnecessary context consumption:

// ❌ Verbose — wastes tokens:
"I have a Next.js project. I'm building an e-commerce site. I have products, categories, a cart, and checkout. I want to add a search feature..."
// ✅ Concise — saves 50%+ tokens:
"Next.js e-commerce site. Add product search to @src/app/products/page.tsx. Search by name and category. Show results in a grid."

---

Comparison: What Each Strategy Saves

| Strategy | Tokens Saved | Effort | Best For | |----------|-------------|--------|----------| | Start new session | Full 200K window | Low | Immediate fix | | CLAUDE.md | ~500-2000 per session | Medium | Long projects | | One session per feature | 50-80% of total | Medium | Complex features | | Decision logs | 30-50% of total | Medium | Multi-session tasks | | 50-message limit | N/A (preventive) | Low | All sessions | | Hooks auto-save | N/A (safety net) | Medium | Heavy users | | Concise prompts | 30-50% per message | Low | All sessions |

---

Summary: What to Do When Context Is Full

Step 1: /save (or write checkpoint)
Step 2: /exit
Step 3: claude
Step 4: @checkpoint.md Continue

Then prevent recurrence with: 1. CLAUDE.md for persistent context 2. One session per feature 3. Decision logs for multi-session work 4. 50-message limit 5. Auto-save hooks 6. Concise prompts

Related Articles: - Claude Code Memory Systems Explained — understand the architecture - Troubleshooting Claude Code Memory Errors — more error-specific fixes - 7 Ways to Speed Up Claude Code — performance tips