Optimizing Context Usage

You asked Claude Code a simple question. It read 40 files, called 12 tools, and by the time it answered, half the context window was gone. For a simple question.

The context window is finite. Every token spent on noise is a token you can't spend on useful work. Good context management is the difference between Claude Code fading halfway through a task and staying sharp to the end.

Where the Tokens Go

Before optimizing, you need to know what's eating your context. Run /context inside Claude Code to see a breakdown. You'll probably be surprised.

Three culprits show up constantly.

MCP server definitions. Every connected MCP server adds its tool definitions to the context window, even if you never use those tools. Five servers connected, one used? Four are dead weight. Prefer CLI tools like gh, aws, or jq over MCP servers when the CLI can do the same job. Fewer servers, less overhead.

Verbose tool output. When Claude Code runs tests, fetches documentation, or processes logs, raw output can be enormous. A full test suite might dump hundreds of lines when you only care about the three that failed. That's a lot of wasted context.

Accumulated conversation history. Every message, every file read, every tool call stays in the window. After a dozen exchanges, the early context is crowding out room for new work.

Run /context right now in an active session. See what's taking up space.

Practical Techniques

Be specific in prompts

You've heard this before and you'll hear it again. Vague prompts force exploration. Specific prompts go straight to the answer.

Bad:  "improve this codebase"
Good: "add input validation to the login function in auth.ts"

The first triggers a broad scan of your entire project. The second reads one file, makes one change. Same outcome quality, fraction of the context cost.

Subagents for noisy work

Subagents run in their own separate context window. They explore, process, then report back a summary. Your main conversation stays clean.

Full test suites, external documentation, build logs, large grep operations. All great candidates for subagent delegation. The noisy work happens elsewhere; you just get the result.

Stop pasting, start pointing

Your instinct might be to paste a git log, a stack trace, or an entire config file into the prompt. Resist that. Tell Claude Code where to look instead.

Bad:  *pastes 200 lines of git log*
Good: "look at the git history for auth.ts over the last week"

Claude Code can read files, run commands, search code. Let it pull exactly what it needs rather than you dumping everything into the conversation.

@file references

Instead of describing where code lives or pasting snippets, use @file references. Claude Code reads on demand and gets the current version, not some stale copy you pasted three messages ago.

Clear between tasks

Working on authentication, then switching to a CSS bug? /clear. The auth context is irrelevant to CSS work. Carrying it forward wastes tokens and can actively mislead the model.

Code intelligence plugins

For typed languages (TypeScript, Go, Rust), code intelligence plugins are a huge win. A single "go to definition" jump replaces what would be a grep across multiple files followed by reading each one. One tool call instead of five.

Context Hygiene

Keep CLAUDE.md lean

Your CLAUDE.md loads into every conversation. If it's 2,000 lines of detailed instructions, that's 2,000 lines consumed before you even ask your first question.

Keep it under 500 lines. Be ruthless about what earns a spot. For specialized knowledge that only applies sometimes, move it into skills. Skills load on demand, so they only cost context when needed.

# CLAUDE.md — keep this focused
## Project Stack
- Next.js 16, TypeScript, Tailwind v4
 
## Key Rules
- Server components by default
- Run npm run build before committing
 
## Skills (loaded on demand)
- "codebase-overview": architecture details
- "testing-patterns": test conventions and utilities

Hooks for preprocessing

Hooks can process tool output before it hits the context window. A hook attached to a command can grep for ERROR and return only matching lines instead of the full log. Same information, 90% fewer tokens.

# Example hook that filters test output
npm test 2>&1 | grep -E "(FAIL|PASS|Error)" | head -20

Scope investigations narrowly

When debugging, don't ask Claude Code to "figure out what's wrong." Point at a specific symptom. "The /api/users endpoint returns 500 when the email field is missing" gives a focused starting point. Fewer files read, fewer commands run, problem solved with context to spare.

This goes beyond debugging, by the way. Code reviews, performance analysis, refactoring planning. Any investigative task benefits from a narrow starting point. Less context burned on exploration.

Try it: Take a task you'd normally describe in a paragraph. Rewrite it as one specific sentence with a file name and function name. Run both versions. The specific version will almost always use less than half the context.

Boiled Down

Run /context regularly so you know what's eating your window. Use subagents for noisy work. Write specific prompts with file names and function names. Keep CLAUDE.md under 500 lines and move specialized knowledge to skills. /clear between unrelated tasks. And seriously, stop pasting things into prompts. Let Claude Code fetch what it needs.