Managing the Context Window

Everything Claude Code knows in a session lives in one place: the context window. It is a fixed-size budget of tokens that holds the system prompt, your tool definitions, every loaded CLAUDE.md and skill, all the files Claude has read, every command it has run, and the entire back-and-forth of your conversation. When that budget is gone, something has to be dropped or compressed.

The number to anchor on is 200K tokens — roughly 1.6 million characters. But you never get all of it for your conversation. The system prompt, tool schemas, your memory files, and a safety buffer all reserve space up front, so the usable window for actual work is closer to 150K-170K tokens.

Here is the part most people miss: the real enemy is quality, not size. Performance degrades as context fills, well before you hit the hard limit. Raw command logs, the same file read five times, a long-finished debugging tangent — all of it stays in the window competing for the model's attention with the three lines that actually matter right now. A window that is 70% full of noise is worse than one that is 40% full of signal. Managing context is really about keeping the signal-to-noise ratio high, not just avoiding the ceiling.

200K-TOKEN WINDOW  (~1.6M chars)
├── System prompt + tool definitions   ┐
├── CLAUDE.md / memory / skills         ├─ reserved overhead
├── Safety buffer (~33K)                ┘
└── YOUR WORKING SPACE  (~150-170K usable)
      files read · commands run · the conversation
      ↑ degrades in QUALITY as it fills, not just at the limit

The window is divided into fixed overhead plus your working space. Knowing the split tells you where your budget actually goes.

A notable 2026 change: the reserved safety buffer was reduced to about 33K tokens (16.5%) of the window. The previous, larger buffer left less room for work; the smaller one gives you roughly 12K more usable tokens than the 2025 default — a free upgrade in working space without changing the 200K headline number.

Note that some configurations support a larger window (up to 1M tokens), but the 200K window is the default you should plan around. Don't assume the big window; design your workflow for 200K and treat anything larger as a bonus.

You can't manage what you can't see. Two commands give you the full picture — one for tokens, one for money.

/context [all] renders a colored grid of where your tokens are going right now: the system prompt, tool definitions, CLAUDE.md, skills, MCP servers, and the conversation itself, each as a slice of the 200K. It also surfaces optimization tips. Run it whenever a session starts feeling heavy — it's how you find the surprise 30K skill or the screenshot that quietly ate a quarter of your window. Pass all for the fully expanded breakdown.

/context        # quick token breakdown + tips
/context all    # fully expanded view of every contributor

/usage (aliases /cost, /stats) reports the cost and consumption side: this session's spend, your plan usage against limits, and — critically — a breakdown by skill, subagent, plugin, and MCP server. That per-source breakdown is how you discover that one chatty MCP server or one runaway subagent is responsible for most of your token (and dollar) burn.

/usage          # session cost + plan usage + per-source breakdown

Think of it as two dashboards: /context answers "what is filling my window right now?" and /usage answers "what is this costing me, and which component is to blame?"

When the window gets heavy you have two fundamentally different tools. Picking the wrong one either loses context you needed or keeps clutter you wanted gone.

/compact [instructions] summarizes the conversation. Claude replaces the long history with a compressed summary that preserves the important parts — code patterns, file states, key decisions — and keeps your CLAUDE.md, skills, and memory intact. You can steer it with an optional focus, e.g. /compact focus on the auth refactor and the failing tests, which tells Claude what to prioritize keeping. Use compact when you want to continue the same task with a lighter, sharper context.

/clear (aliases /reset, /new) resets the context entirely — an empty window, as if you just started. It does not undo file edits (your code on disk is untouched) and the prior conversation is still resumable via /resume. Use clear when you're switching to an unrelated task; carrying the old conversation's residue into new work is the classic 'kitchen-sink' anti-pattern that bloats context for no benefit.

The rule of thumb: same task, getting heavy → compact. New, unrelated task → clear.

Compaction isn't one thing — three distinct mechanisms operate at different times, and understanding the differences is what separates fumbling from control.

Microcompaction clears stale tool results — old command output and file reads that are no longer relevant — without making a model call. It's cheap, automatic, and surgical: it trims the low-value clutter (the noise) while leaving your conversation and decisions fully intact. No summarization, no cost, no lost reasoning.

Auto-compaction kicks in automatically as you approach the limit. It summarizes the conversation — code patterns, file states, key decisions — into a compressed form so the session can keep going. It's the safety net that stops you from hitting a hard wall mid-task, but because it fires near 95% full and you don't control its timing, the summary is often coarser and the model is already operating in a degraded, crowded window.

Manual /compact is you choosing the moment. And the moment matters enormously.

This is the single most valuable habit in the lesson. Run /compact manually at around 60% full — not at 95%.

Why early beats late:

• Sharper summaries. At 60%, Claude has plenty of headroom to write a thorough, well-organized summary. At 95%, auto-compaction is summarizing under pressure in an already-degraded window — the result is coarser and loses more.
• Cheaper. Summarizing a 60%-full window costs less than summarizing a 95%-full one, and you avoid the quality tax of working in a crowded window in the meantime.
• You control the focus. A manual /compact focus on X lets you tell Claude exactly what to preserve. Auto-compaction makes that call for you, and it can guess wrong.
• No surprise stalls. Waiting for auto-compaction means it fires mid-task at an unpredictable moment. Compacting proactively keeps you in command of when the pause happens.

The practical loop: keep /context handy, and when working space crosses roughly 60%, run /compact with a focus instruction. Treat auto-compaction as the emergency backstop you'd rather never hit — not your default behavior.

0% ────────── 60% ────────── 95% ───── 100%
               ▲                ▲
         compact HERE     auto-compaction
         (manual, sharp)   (backstop, coarse)

Because any summary is lossy, you sometimes need to guarantee that a specific piece of context survives a compaction. The lightweight way to do this is to tell CLAUDE.md what to keep.

Add a line to your project's CLAUDE.md in the form 'when compacting, preserve X' — for example, naming the API contract, the migration plan, or the invariant the whole task depends on. Because the project-root CLAUDE.md is re-injected from disk after a /compact, that instruction is present when Claude builds the summary, nudging it to retain what you flagged.

## Context management
- When compacting, preserve: the database migration order, the
  public API contract in api/contract.md, and any decision marked DECISION:.
- Do not summarize away open TODO items; keep them verbatim.

This is advisory, not a hard guarantee — CLAUDE.md is delivered as context, so compliance is a strong nudge rather than a lock. For things that absolutely must not be lost or violated (like 'never push to main'), reach for a deny permission rule or a hook instead, which are enforced deterministically. Use the CLAUDE.md preserve-line for content you want carried forward, and rules/hooks for boundaries that must hold.