Context management in Claude Code

Up to date as of April 2026.

Claude Code never tells you the context is the problem. It just gets quietly worse — vaguer answers, decisions it agreed to an hour ago and no longer remembers, suggestions that contradict its own earlier ones. I spent months reading that as the model having a bad day.

The main principle

The context window is your most important resource, and the easiest way to make Claude Code feel worse is to keep piling things into one session and hope it somehow stays sharp. Everything counts: every message, every file read, every command result, every answer back from Claude. As the window fills up, quality drops before you notice it.

Context size depends on the model you’re running. Some models have extended context (including 1M-token variants), but the only number that matters is the one in your session: check /context.

What loads automatically at startup

Before you type anything, some of the window is already spoken for:

System prompt and built-in tools
Your CLAUDE.md and any imported files
Auto memory, if enabled
Skill list metadata
MCP server tool definitions, if enabled

That’s why two sessions with the same prompt can still behave differently — different MCP servers, different memory files, different imported rules. Run /context to see the real breakdown. Run /memory to see which files actually loaded.

Monitoring

I check these two more than any other commands when Claude starts feeling “off”:

/context    # breakdown by category: what takes how much
/memory     # which CLAUDE.md and auto memory files are loaded

The status line at the bottom shows fill % in real time.

Context management commands

`/clear`

Full reset. CLAUDE.md reloads, history disappears. Use it when switching to a different task, or when a session has clearly gone sideways and you’d rather start fresh than fight the accumulated mess.

`/compact [instruction]`

Claude summarizes the conversation and replaces the history with a brief summary. You can tell it what to keep:

/compact focus on the authentication changes we made
/compact keep the list of modified files and test commands

Reach for this when context is filling up but you’re not done yet — /compact keeps you in the session without losing the thread. If I could keep only one command on this page, it would be this one. Summarizing without starting over has saved more sessions than anything else here.

`/btw question`

A quick side question that doesn’t go into the main conversation:

/btw what type does this function return?
/btw is there a built-in for this in Python?

Useful for quick clarifications that you don’t want clogging up the main thread.

`/rewind` (or double Esc)

Opens a restore menu. You can roll back the conversation, the code, or both. Use this when Claude went the wrong direction and you want to try a different approach from a clean state.

Autocompact

Auto-compaction is the safety net, not the primary strategy.

It kicks in automatically when context usage gets close to full.

If you want it to happen earlier, Claude Code documents this env var:

// ~/.claude/settings.json
{ "env": { "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75" } }

That sets the threshold as a percentage of available context. Default behavior is roughly 95%. Lower values compact earlier. The setting applies to both the main conversation and subagents.

I don’t set it. In practice I reach for /compact by hand long before autocompact would fire — waiting for 95% is waiting until you’re out of gas to start looking for a station. The override is there if you’d rather not think about it at all.

If you’re using an extended-context model and want compaction math based on a smaller effective window, Claude Code also documents CLAUDE_CODE_AUTO_COMPACT_WINDOW.

Either way, know what survives it: Claude re-reads CLAUDE.md from disk, but ad-hoc instructions that existed only in the conversation can be lost. If something matters, move it into CLAUDE.md before you compact.

What eats the most context

1. MCP tool definitions

Every connected MCP server dumps descriptions of all its tools into context at startup. One tool is 550–1,400 tokens. An MCP server with fifty tools is 30k+ tokens before you’ve typed anything.

Fix: only connect servers you actually need. /mcp lets you disable the rest — that’s what it’s for.

2. Reading large files

Every file Claude reads lands fully in context. No excerpts, no summaries.

Fix: use subagents for open-ended exploration, and give Claude the exact file path instead of “look around the auth system.” Vague requests → Claude reads everything.

3. Long conversations

Just accumulated history.

Fix: /clear between tasks, /compact within a task.

Habits that keep context small

Most context problems are workflow problems in disguise. None of what follows is about the context window directly — it’s about not generating the mess in the first place.

Give Claude a way to verify the result

This is the most important one. Claude works significantly better when it can check its own work:

# Bad
"implement email validation"

# Good
"write validateEmail function. test cases: user@example.com -> true,
invalid -> false, user@.com -> false. run tests after implementing."

Without verification criteria Claude can produce something that looks right but doesn’t work.

Explore -> Plan -> Code -> Commit

Separate exploration and implementation. The session that reads widely is usually not the session you want doing the final edit.

Plan mode — Claude reads files, builds a plan, changes nothing
You approve the plan
Normal mode — implements according to plan
Commit

# Enable plan mode at launch
claude --permission-mode plan
# or Shift+Tab inside a session

Plan mode is the thing I resisted longest and now use most, for an unglamorous reason: approving a plan is much cheaper than reviewing a diff.

Specific prompts save context

The more specific the prompt — the fewer iterations and less context spent:

# Bad — triggers many clarifying questions
"add a calendar widget"

# Good — everything is clear immediately
"look at HotDogWidget.php to understand widget patterns.
implement a calendar widget in the same style with month
selection and year pagination. no new libraries."

Subagents for exploration

Codebase exploration reads many files — all of it pollutes the main context:

# Bad — Claude reads everything in the main context
"investigate how our auth system handles token refresh"

# Good — subagent works in its own context
"use a subagent to investigate how our auth system handles
token refresh and whether we have OAuth utilities to reuse"

The subagent returns a brief summary — the main context stays clean. Be honest about the trade: that summary is worse than what you’d have gotten reading the files yourself. You’re buying a cleaner main context with a thinner understanding of what’s in it.

`/clear` between unrelated tasks

# Done with auth -> starting UI work
/clear

# Now a clean context without leftovers from the auth task

After two failed corrections — reset and start over

Two is the count that works for me. The third correction almost never lands, and the fourth definitely doesn’t. /clear, then write the prompt you should have written first, using everything the failed attempts just taught you.

Use `@` to reference files

@src/api/auth.ts look at how this file works

Instead of describing where things are — give a direct reference.

Pipe data directly

cat error.log | claude -p "what's going on here?"
gh pr diff | claude -p "summarize this PR"

Workflows for different task sizes

This is the simplest mental model I know:

Small task (typo, rename, quick fix)

-> Just write what you need, no planning
-> Claude does it
-> You verify

Medium task (new endpoint, feature)

-> Plan mode: "read src/api/ and plan how to add X"
-> Approve the plan
-> Normal mode: "implement"
-> Run tests
-> Commit

Large task (refactoring, migration)

-> Separate session for exploration with subagents
-> Write spec to a file
-> New clean session for implementation
-> Worktrees for parallel parts

When it’s already going wrong

Every habit above is cheap if you apply it early, which is exactly the problem — the signals all arrive late. Three I’ve learned to catch.

The session drifted. I started with one thing and I’m now three things deep. It begins as “fix the login bug” and two hours later I’m asking about CSS in a context that has read 40 TypeScript files. The bug is fixed, but Claude has opinions about the auth layer and the button spacing.

I’m arguing. Same mistake corrected twice and still wrong on the third try — because the context is carrying every broken approach we’ve been through, and each new correction has to fight all of them at once.

I stopped checking. Claude produced something that looked right and I shipped it without ever giving it a way to prove it worked.

If a session starts feeling muddy, it usually is. Reset earlier than your instincts say to.

Checkpoints and resume

Claude automatically creates checkpoints before every change. It’s not a replacement for git, but lets you roll back:

Esc + Esc  # or /rewind — open checkpoint menu

Sessions are saved locally:

claude --continue         # continue the last session in this directory
claude --resume           # pick from recent sessions
claude --resume auth-refactor
/rename             # name a session ("oauth-migration")

Parallel sessions for scaling

When you need more:

# Multiple worktrees — multiple independent Claude instances
git worktree add ../proj-auth feature/auth
git worktree add ../proj-ui feature/ui

cd ../proj-auth && claude &
cd ../proj-ui && claude &

Writer/Reviewer pattern:

Session A: implements the feature
Session B: reviews with a clean context (not biased toward the code it just wrote)

Fan-out for batch operations:

for file in $(cat files.txt); do
  claude -p "migrate $file from React to Vue" \
    --allowedTools "Edit" "Bash(git commit:*)"
done

Command cheatsheet

Command	When
`/context`	See what takes how much space
`/clear`	New task or polluted context
`/compact`	Task continues, need to free space
`/compact focus on X`	Compaction preserving specific details
`/btw question`	Quick side question outside the main thread
`/rewind` or `Esc+Esc`	Roll back to a previous state
`Esc`	Stop Claude mid-response
`/mcp`	Disable unused MCP servers
`--permission-mode plan`	Read-only mode before implementation
`claude --continue`	Continue a previous session