How to Monitor Context Window Usage in Claude Code with Claude HUD

Mar 21, 2026

Problem

I was in the middle of a complex refactoring task when Claude suddenly stopped responding properly. The conversation had grown long, and I had no warning that I was approaching my context limit.

Claude: I apologize, but I'm having trouble with the context...

[Session becomes unreliable, previous context lost]

This was frustrating. I needed to know how much context window I had left before it became a problem. Running /context manually every few minutes was tedious and broke my flow.

What I Wanted

I needed real-time visibility into my context usage without leaving my workflow. Specifically:

See how much context I’ve used at a glance
Get warned before hitting limits
Know when to start a fresh conversation
Understand what’s consuming my context (files, conversation history, etc.)

The Solution: Claude HUD’s Context Bar

After installing Claude HUD, I got a context bar that shows exactly this information:

Context █████░░░░░ 45% | Usage ██░░░░░░░░ 25% (1h 30m / 5h)

The context bar appears in the status line below my input. It updates automatically as I work, showing my context consumption in real-time.

Color-Coded Warnings

What I found most useful is the color coding:

| Threshold | Color | Meaning              |
|-----------|-------|----------------------|
| <70%      | Green | Normal operation     |
| 70-85%    | Yellow | Warning - plan ahead |
| >85%      | Red   | Critical - act now   |

When my context bar turns yellow, I know I should start wrapping up or plan a context reset. When it turns red, I see a token breakdown:

Context ████████░░ 87% (in: 120k, cache: 45k, out: 15k)

This breakdown tells me exactly what’s consuming my context:

in: Input tokens (conversation history, file reads)
cache: Cached tokens (reused context from prompt caching)
out: Output tokens (Claude’s responses)

Display Modes

I can configure how the context displays:

Percent mode (default):

Context █████░░░░░ 45%

Tokens mode:

Context 90k/200k

Remaining mode:

Context 55% remaining

To change display modes, I run:

/claude-hud:configure

Then select my preferred context display format.

How It Works

I was curious about the accuracy. Unlike some tools that estimate token counts, Claude HUD uses native data from Claude Code itself.

The data comes from Claude Code’s stdin JSON stream:

export interface StdinData {
  context_window?: {
    context_window_size?: number;
    current_usage?: {
      input_tokens?: number;
      output_tokens?: number;
      cache_creation_input_tokens?: number;
      cache_read_input_tokens?: number;
    } | null;
    used_percentage?: number | null;
    remaining_percentage?: number | null;
  };
}

This means the percentages match what you’d see if you ran /context manually. The HUD just displays it continuously instead of on-demand.

Scaling for Different Models

Different Claude models have different context limits:

Claude 3.5 Sonnet: 200k tokens
Claude 3 Opus: 200k tokens
Some models: up to 1M tokens

The HUD automatically scales based on the model’s context window size. I don’t need to configure anything—it detects the limit and calculates percentages accordingly.

Why This Matters

Context limits are a real constraint in Claude Code. When you hit them:

Responses truncate: Claude stops mid-response
Context loss: Earlier conversation becomes unavailable
Work disruption: You must start a new session
Time waste: Re-explaining context to a fresh session

With real-time monitoring, I can:

Plan context resets at convenient points
Batch file reads strategically
Know when to summarize and continue vs. start fresh
Avoid unexpected truncation during critical work

Configuration

The context bar can be customized in ~/.claude/settings.json:

{
  "display": {
    "contextValue": "percent",
    "showTokenBreakdown": true
  },
  "colors": {
    "context": "blue"
  }
}

Options for contextValue:

"percent": Shows percentage with progress bar
"tokens": Shows raw token counts
"remaining": Shows remaining percentage

I keep showTokenBreakdown enabled so I see the detailed breakdown when crossing 85%.

When to Reset Context

With visibility into my context usage, I’ve developed a pattern:

< 50%   : Continue freely, read any files needed
50-70%  : Be mindful, prefer smaller context reads
70-85%  : Plan wrap-up, summarize key decisions
> 85%   : Start fresh session, carry forward summaries

This prevents the frustrating scenario where I’m 90% done with a task and suddenly lose context.

What I Learned

The context bar changed how I work with Claude Code:

I stopped hitting context limits unexpectedly: The yellow warning at 70% gives me time to plan.
I understand my usage patterns: Seeing “cache: 45k” shows me when prompt caching is working vs. when I’m reading new files constantly.
I can optimize session length: Instead of guessing when to start fresh, I have data.
I avoid truncation: The red zone at 85% with token breakdown shows exactly what’s consuming context, so I can decide whether to continue or reset.

The key insight: Claude HUD’s context monitoring isn’t just about watching numbers. It’s about giving you control over when and how you manage your context limits, instead of being surprised by them.

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 HUD GitHub

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