The Complete Guide to Claude Code Context Management: Making Every Token Count

Introduction

In my advanced guide, I covered context management basics in about 40 lines. But after extensive daily use, I've found that context management is the most underrated yet most impactful skill in Claude Code.

You can have a perfect CLAUDE.md and well-configured Hooks — if your context management is sloppy, Claude will still give you off-base answers.

This post covers context management thoroughly.

Why Context Management Matters

Claude Code's context window is finite. Think of it as a workbench:

• The surface area is limited (context window size)
• The more stuff you pile on, the harder it is to find things (quality degrades)
• Once it's full, nothing new fits (truncation or auto-compression)

Poor context management leads to:

Bottom line: a fuller context window isn't better — a more precise one is.

What's in the Context

Understanding what occupies the context is the first step to managing it. A typical Claude Code session breaks down roughly like this:

Key takeaways:

1. Tool call results are the biggest consumer — Every file read, every command execution dumps results into context. Reading a 500-line file costs 500 lines of context
2. More back-and-forth = faster consumption — Each conversation turn (your input + Claude's output) accumulates
3. CLAUDE.md is always there — It's loaded at the start of every conversation, so keeping it concise matters (see my CLAUDE.md guide)

Core Commands

The advanced guide listed four commands briefly. Here's the deep dive on when and why to use each.

/clear — Fresh Start

/clear

What it does: Completely wipes the current conversation context, returning to initial state (system prompt + CLAUDE.md).

When to use:

• Switching to a completely different task (from fixing a bug to building a new feature)
• Context is "polluted" (Claude insists on wrong assumptions no matter how you correct it)
• Current task is done, ready for the next one

Note: /clear is irreversible. Make sure the current task is complete or you don't need the context before clearing.

/compact — Compress and Continue

/compact                              # Default compression
/compact Keep only architecture decisions and TODOs  # Custom prompt

What it does: Has Claude summarize the current conversation, replacing full history with a concise summary.

When to use:

• Task is mid-progress but context is getting full
• Want to keep key decisions and progress, discard intermediate trial-and-error
• After a long debugging session, keep conclusions but drop debug details

Custom compression prompts are key. Default compression might drop info you consider important. Tell Claude what to keep:

/compact Keep: 1. Current file change list 2. Confirmed bug cause 3. Next steps

/context — Check Usage

/context

What it does: Shows current context window usage, including tokens used and remaining space.

When to use:

• Responses feel slower, want to confirm if context is nearly full
• Before deciding between /clear and /compact, check how much is used
• Build the habit: check after completing each subtask

/resume — Restore Session

/resume                     # Interactive session picker
claude --resume             # Resume last session on startup
claude --resume SESSION_ID  # Resume specific session

What it does: Restores a previous session's context to continue unfinished work.

When to use:

• Continuing yesterday's task today
• Accidentally closed the terminal, want to recover progress
• Switching between tasks (pause task A, do B, return to A)

Note: Restored sessions consume context space. If the previous session was already long, you may need to /compact soon after resuming.

Context Feeding Techniques

Beyond managing context, how you feed information to Claude matters just as much.

Pipe Input

# Feed file contents
cat src/lib/api.ts | claude "analyze error handling in this file"
 
# Feed git diff for code review
git diff main | claude "review these changes, focus on security"
 
# Feed build errors
npm run build 2>&1 | claude "analyze build errors and suggest fixes"
 
# Feed test results
npm test 2>&1 | claude "analyze failing test cases"
 
# Feed multiple files
cat src/models/user.ts src/routes/auth.ts | claude "analyze data flow between these files"

The advantage of pipe input is precision — you give Claude exactly what it needs, nothing more.

@-Mentions

Reference files with @ in conversation:

You: @src/components/Navigation.tsx the mobile menu in this component has a bug — it doesn't close after clicking

Claude automatically reads the file. Faster and more precise than letting Claude search for files on its own.

Image Input

# Feed screenshots
claude "what's wrong with this UI?" -i screenshot.png
 
# Feed design mockups
claude "implement a component matching this design" -i design.png

Structured Prompts

Reducing back-and-forth is the most effective way to save context. Give complete requirements upfront:

You: Refactor the Navigation component:
1. Replace inline styles with Tailwind classes
2. Use Dialog for mobile menu instead of current div
3. Add keyboard navigation (Escape to close, Tab cycling)
4. Keep existing i18n support intact
Reference: @src/components/Navigation.tsx

Compare the inefficient approach:

You: Look at the Navigation component
Claude: (reads file, outputs analysis)
You: Refactor it
Claude: What aspects do you want to refactor?
You: Change styles to Tailwind
Claude: (modifies styles)
You: Also add keyboard navigation
...

The second approach consumes 3-4x the context of the first.

Context Pollution and Recovery

"Context pollution" is when incorrect information, outdated assumptions, or contradictory instructions accumulate in the context, degrading Claude's output quality.

Common Pollution Scenarios

How to Tell If Context Is Polluted

A few signals:

1. Claude gets "stubborn" — You correct it, but it makes the same mistake next turn
2. Answers become vague — Previously precise responses turn fuzzy
3. Ignores CLAUDE.md rules — Rules it was following suddenly get ignored
4. Hallucinations — References non-existent functions, files, or APIs

Recovery Strategies

Mild pollution → /compact with custom prompt:

/compact Ignore all previous discussion about approach A, keep only approach B decisions and current progress

Moderate pollution → /clear + re-provide key context:

/clear
# Then restart with correct context in one go

Severe pollution → New session:

Close the terminal and start a fresh Claude Code session. Sometimes this is the fastest fix.

Session Strategies

Long Sessions vs Short Sessions

Rule of thumb: If a task exceeds 20 conversation turns, consider /compact or splitting into multiple short sessions.

Task-Based Session Planning

Recommended workflow:

Session 1: Planning
  → Analyze requirements, decide approach, output task list
  → /clear

Session 2: Implementation
  → Implement tasks one by one
  → /context after each subtask
  → /compact when context exceeds 60%
  → /clear

Session 3: Testing and Fixes
  → Run tests, fix bugs
  → /clear

Session 4: Review and Wrap-up
  → Code review, docs update, commit

Multi-Terminal Parallelism

For large tasks, run multiple terminals in parallel:

# Terminal 1: Frontend components
claude "refactor the Navigation component"
 
# Terminal 2: Backend logic
claude "optimize getPostsByLocale performance"
 
# Terminal 3: Tests
claude "add edge case tests for posts.ts"

Each terminal has its own independent context. This is the cleanest way to parallelize.

Practical Example 1: General Development

Scenario: Adding full-text search to a blog.

Phase 1: Planning (New Session)

claude

You: I want to add Pagefind full-text search to my Next.js blog.
Current search is URL query filtering, see @src/components/SearchBar.tsx
Requirements:
1. Generate search index at build time
2. Client-side search component to replace existing SearchBar
3. Support Chinese and English
4. Maintain existing URL query compatibility

Give me a technical plan first, don't write code.

After Claude outputs the plan:

/clear    # Planning done, clear context

Phase 2: Implementation (New Session)

claude

You: Implement Pagefind search with this plan:
1. Install pagefind, add postbuild script to next.config.ts
2. Create new SearchBar component using @pagefind/default-ui
3. Chinese support via pagefind's CJK tokenizer
Start with step 1.

After each step:

/context   # Check context usage

If over 60%:

/compact Keep: completed steps, current file change list, next steps

Phase 3: Testing (New Session)

npm run build 2>&1 | claude "build failed, help me analyze"

Pipe the error log directly — precise and efficient.

Practical Example 2: Flutter Development

Scenario: A complex state management bug in a Flutter app — user updates their avatar on ProfileScreen, but HomeScreen doesn't reflect the change.

Phase 1: Diagnosis (New Session)

claude

You: Flutter app has a state sync bug:
- User updates avatar on ProfileScreen, HomeScreen avatar doesn't update
- State management: Riverpod
- Relevant files:
  @lib/providers/user_provider.dart
  @lib/screens/profile_screen.dart
  @lib/screens/home_screen.dart
  @lib/widgets/avatar_widget.dart

Analyze possible causes first, don't modify code.

Claude analyzes and confirms the userProvider isn't properly notifying listeners on state change.

/compact Keep: bug cause is userProvider creates new state object in updateAvatar but doesn't trigger notifyListeners, need to fix user_provider.dart updateAvatar method

Phase 2: Fix (Continue Current Session)

You: Confirmed. Fix the updateAvatar method in user_provider.dart to ensure state changes notify all listeners.

After the fix:

/context   # Check usage

Phase 3: Verification (New Session If Needed)

If context is still comfortable (< 50%), continue:

You: Fix looks correct. Now check if similar issues exist elsewhere — search all providers for direct state property mutations without copyWith.

If context is getting full (> 70%), start fresh:

/clear

You: Just fixed a Riverpod state sync bug (provider wasn't creating new state properly on update).
Check if other providers in the project have similar issues.
Focus on @lib/providers/ directory.

Flutter-Specific Context Tips

# Feed analysis results
flutter analyze 2>&1 | claude "analyze these lint warnings"
 
# Feed build errors
flutter build apk 2>&1 | claude "analyze build errors"
 
# Feed test results
flutter test test/unit/providers/ 2>&1 | claude "analyze failing tests"
 
# Feed specific widget test
flutter test test/widget/home_screen_test.dart 2>&1 | claude "why is this widget test failing"

Context management tips for Flutter projects:

1. Widget trees run deep — Don't have Claude read too many nested Widget files at once; focus on the 2-3 relevant ones
2. Clarify state flow — Explicitly state where data comes from and where it goes in your prompts
3. Mention platform differences upfront — If a bug only occurs on iOS/Android, say so early
4. pubspec.yaml is valuable — Have Claude read pubspec.yaml first to understand dependency versions and avoid incompatible suggestions

Advanced Tips

Auto-Compact Settings

Claude Code supports automatic compression when context approaches the limit. Configure in settings.json:

{
  "autoCompact": true
}

When enabled, Claude auto-compresses once context usage exceeds the threshold.

You can also set a custom compression prompt so auto-compact retains what you care about:

{
  "autoCompact": true,
  "compactPrompt": "Keep: file change list, architecture decisions, TODOs. Discard: intermediate debugging, resolved errors."
}

CLAUDE.md and Context Efficiency

CLAUDE.md is loaded into context at the start of every conversation. So:

• Keep it concise — Every extra line in CLAUDE.md is one less line for actual work
• Use the hierarchy — Global CLAUDE.md for universal rules, project-level for project specifics, subdirectory-level for module rules
• Avoid duplication — Don't repeat what's already in framework documentation

See my CLAUDE.md guide for detailed writing tips.

Memory Files

Claude Code supports persistent memory files (in the ~/.claude/ directory). Write cross-session information to memory files instead of repeating it in every conversation:

# Claude automatically reads memory files
# Good for: project architecture overview, common commands, personal preferences

Memory files vs CLAUDE.md:

Combining Hooks for Context Efficiency

Use Hooks to automate repetitive work, reducing conversational back-and-forth:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

With this Hook, you never need to say "format that for me" in conversation. Every saved conversation turn is saved context.

FAQ

Q: How do I choose between /compact and /clear? A: Task unfinished → /compact (preserve progress). Task done or switching tasks → /clear (clean slate).

Q: What happens when context is full? A: Claude Code auto-compresses earlier conversation. But auto-compression isn't as precise as manual /compact, because it doesn't know what you consider important.

Q: Pipe input or @-mentions — which is better? A: Pipe input for dynamic content (command output, error logs). @-mentions for static files. You can mix both.

Q: How long is "too long" for a session? A: No absolute rule. But if Claude starts forgetting earlier agreements or responses slow down noticeably, it's time to /compact or /clear. Generally check after 20-30 conversation turns.

Q: Will a /resume'd session fill up quickly? A: Yes. Restored sessions carry the full previous context. If the previous session was already long, /compact immediately after resuming — keep only what you need to continue.

Q: How do I stop Claude from reading unnecessary files? A: Explicitly specify relevant files in your prompt (use @-mentions) so Claude doesn't need to explore. Also, a well-written CLAUDE.md with clear project structure helps Claude locate the right files faster.

Conclusion

Context management boils down to three things:

1. Know what's in your context — Monitor with /context, understand the context cost of each operation
2. Keep context clean — /compact or /clear promptly, don't let useless info pile up
3. Feed context precisely — Use pipes, @-mentions, and structured prompts to get it right in one shot

Treat context management as a habit, not a last resort when things go wrong.

Further Reading

• Claude Code Advanced Guide — Where context management was first introduced
• The Complete Guide to CLAUDE.md — A well-written CLAUDE.md is the foundation of context efficiency
• The Complete Guide to Claude Code Hooks — Use Hooks to reduce repetitive conversations
• Claude Code Documentation — Official documentation