Context Management

Manage Claude Code's context window: what loads, what survives compaction, and how to keep long sessions useful.

Why Context Management Matters

Claude Code works inside a finite context window. Every instruction, file read, tool result, MCP schema, skill body, and conversation turn competes for space.

Good context management is not just about saving tokens. It is about keeping the right information visible at the moment Claude needs it.

What Loads Into Context

Claude Code builds context from multiple sources:

This is why a short prompt can still enter a large context. The runtime is carrying project instructions, tool affordances, and session history around it.

Core Commands

/context

Shows a visual breakdown of context window usage:

/context

Use it when a session starts feeling slow, repetitive, or forgetful.

/compact

Compresses the current conversation while trying to preserve useful state:

/compact
/compact focus on the auth refactor decisions and failing tests

Claude Code also compacts automatically as the window approaches capacity. Treat automatic compaction as a safety net, not a planning strategy.

/clear

Clears conversation history for an unrelated task:

/clear

After /clear, persistent context such as CLAUDE.md, rules, memory, and tool availability can still load again. The old conversation does not remain as working context.

@ References

Load targeted files or directories:

Look at @src/auth/session.ts and @src/auth/refresh.ts.
Why does the refresh token expire early?

Use @ when you already know the relevant files. Use subagents when you do not.

Compaction Strategy

Compaction is useful, but it is lossy. It should preserve decisions, file paths, current tasks, important errors, and next steps. It should not preserve every log line or tool output.

Before a long compact, help Claude by naming what matters:

/compact keep:
- current branch and files changed
- the three rejected approaches
- failing test names and error messages
- the plan we agreed to implement next

After compaction, ask for a checkpoint summary if the task is risky:

Before editing again, restate the current plan, changed files, and known risks.

Keep the Main Window Clean

Use the right container for each kind of information:

The main context window should hold the task state, not every artifact discovered while reaching it.

Practical Patterns

• Clear between unrelated tasks. Context from a bug investigation can bias a feature build.
• Use /context before blaming the model. Many quality drops are context hygiene problems.
• Reference files directly. @src/api/users.ts beats "look through the API."
• Delegate broad search. A subagent can explore a large module and return a small evidence-backed report.
• Compact with intent. Tell Claude what to preserve before a long session crosses the limit.
• Move recurring context out of chat. If you say the same instruction twice, it might belong in CLAUDE.md, rules, or a skill.

Anti-Patterns

• Huge CLAUDE.md files: every session pays the token cost.
• Pasting entire logs: summarize or pipe only the relevant excerpt unless the full log matters.
• Loading ten files before asking a question: start with the likely two or three.
• Letting tool output pile up: use subagents, --output-format, or targeted commands.
• Treating compaction as perfect memory: verify critical decisions after compaction.

Related Reading

• Claude Code Architecture — Where context sits in the harness
• CLAUDE.md & Memory — Persistent context sources
• Subagents — Isolate noisy exploration
• Skills — Keep reusable procedures out of the main window