How to visualize Claude Code context window and token usage when debugging sessions

Mar 24, 2026

I was working on a large codebase refactoring task with Claude Code when suddenly my context window hit its limit. The session just stopped working properly, and I had no idea why. All I saw was a vague progress bar in the UI—no breakdown, no explanation of what was eating my tokens.

Context: ████████████████████░░░░░░░░░░ 67%

That's it. No details. No breakdown. Just a bar.

I needed to understand what was happening. Was it my CLAUDE.md files? Tool outputs? Something else entirely?

Environment

Claude Code CLI
Large codebase with multiple CLAUDE.md configuration files
Long-running refactoring session with multiple tool calls
macOS/Linux terminal

What Happened

I started a refactoring task that involved reading multiple files, running tests, and making changes across dozens of files. After about 20-30 turns, things started getting slow. Then I hit the context limit.

Warning: Context window is nearly full. Consider starting a new session
or using /compact to reduce context size.

The problem was: I had no visibility into what was consuming my context. The UI showed a progress bar, but that’s useless for debugging. I needed to know:

How many tokens are my CLAUDE.md files using?
Are tool outputs bloating my context?
How much thinking is Claude doing?
What gets dropped during compaction?

The Solution: claude-devtools

After some research, I found claude-devtools—a tool that gives you granular visibility into your context window.

Installation

npm install -g claude-devtools

Running with DevTools

claude-code --devtools

Once enabled, you get a detailed breakdown of your token usage across 7 categories:

Token Breakdown (Turn 25):
────────────────────────────────────────────
CLAUDE.md files:    2,450 tokens (4.9%)
Tool inputs:        8,320 tokens (16.6%)
Tool outputs:       15,680 tokens (31.4%)
Thinking tokens:    4,200 tokens (8.4%)
Skill activations:  1,100 tokens (2.2%)
User text:          890 tokens (1.8%)
System overhead:    17,360 tokens (34.7%)
────────────────────────────────────────────
Total: 50,000 tokens / 200,000 limit (25%)

This was exactly what I needed. Now I could see that tool outputs were my biggest consumer at 31.4%.

Why This Matters

Context window management directly impacts your productivity and costs. Here’s what I learned from the breakdown:

1. Tool Outputs Are the Silent Killers

I had no idea that reading large files would add their entire contents to my context:

const result = await readFile('large-config.json')
// This 50KB file added ~12,500 tokens to my context!

After seeing the devtools breakdown, I started using limits:

const result = await readFile('large-config.json', { limit: 100 })
// Only ~2,500 tokens now

2. CLAUDE.md Files Add Up

I had several CLAUDE.md files with overlapping instructions. The devtools showed me they were using 2,450 tokens combined. I consolidated them:

# project-root/CLAUDE.md (800 tokens)
# project-root/src/CLAUDE.md (600 tokens)
# project-root/src/components/CLAUDE.md (550 tokens)
# project-root/src/utils/CLAUDE.md (500 tokens)

# project-root/CLAUDE.md (1,200 tokens)
// Removed duplicate instructions, kept essential context

3. Thinking Tokens Count Too

I assumed thinking/reasoning tokens were “free.” They’re not. They count toward your limit. When Claude goes into extended reasoning mode:

Turn 18: Thinking spike
────────────────────────────────────────────
Thinking tokens: 12,500 tokens (25%)
Reason: Complex architecture decision
────────────────────────────────────────────

4. Compaction Events Are Traceable

When context gets too large, Claude Code compacts it. With devtools, I could see exactly what got dropped:

[Compaction Event - Turn 32]
Dropped: Turns 1-15 user messages and tool outputs
Retained: CLAUDE.md files, recent turns, critical context
Context reduced: 180,000 -> 95,000 tokens

Common Mistakes I Made

Ignoring CLAUDE.md size until hitting limits - I should have checked this earlier
Not understanding tool outputs consume context - Every file read adds tokens
Assuming thinking tokens were free - They absolutely count
Resetting sessions unnecessarily - Targeted optimization would have worked
Overlooking skill activations - Some skills add hidden token costs

Context Window Timeline View

The devtools also provides a timeline showing how your context fills during a session:

Turn │ Context Usage │ Major Events
─────┼───────────────┼──────────────────────────
  1  │     5,000     │ Session start
  5  │    15,000     │ First file reads
 10  │    35,000     │ Test runs begin
 15  │    60,000     │ Large refactoring starts
 20  │    95,000     │ Multiple file edits
 25  │   125,000     │ Extended thinking on architecture
 30  │   165,000     │ Approaching limit
 32  │   180,000     │ **COMPACT EVENT**
 33  │    95,000     │ Context reduced
 35  │   110,000     │ Continued work

This timeline helped me identify exactly which turns were token-heavy and why.

Optimizing Based on Insights

After using devtools for a few sessions, here’s my optimization checklist:

[ ] Review CLAUDE.md files for redundancy
[ ] Use file read limits when possible
[ ] Be aware of thinking token costs for complex reasoning
[ ] Check skill activation overhead
[ ] Monitor tool output accumulation
[ ] Consider session reset vs. continuation strategically

Summary

In this post, I showed how to visualize Claude Code’s context window and token usage using claude-devtools. The tool breaks down token consumption across 7 categories (CLAUDE.md files, tool call inputs/outputs, thinking tokens, skill activations, user text) and shows how context fills up over time. The key insight is that visibility leads to optimization—once you can see what’s consuming your context, you can make informed decisions about reducing it.

Without devtools, you’re flying blind with just a progress bar. With devtools, you get actionable data that helps you optimize your Claude Code sessions and reduce costs.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Claude DevTools GitHub
👨‍💻 Reddit Discussion: Claude DevTools

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!