What is Claude HUD? A Real-Time Statusline Plugin for Claude Code

Mar 21, 2026

Purpose

This post introduces Claude HUD, a plugin that displays real-time context usage, tool activity, and rate limits directly in Claude Code’s statusline. The key point is that it gives you visibility into your AI coding session without requiring separate windows or tmux panes.

The Problem

When I work with Claude Code on long coding sessions, I run into three frustrating problems:

Problem 1: Context Window Limits

I’m in the middle of a complex refactoring. Suddenly Claude stops understanding my earlier context. I hit the 200k token limit without warning. Now I have to start a new session and re-explain everything.

Problem 2: Rate Limits

I’m on Claude Pro with a 5-hour usage limit. I don’t know how much I’ve used. Then I get the dreaded message: “You’ve reached your usage limit.” My workflow stops cold.

Problem 3: Hidden Activity

Claude is running a complex task with multiple tools. I see nothing happening in the terminal. Is it stuck? Is it thinking? Is it waiting for something? I have no visibility.

I needed a way to see what’s happening in real-time.

The Solution

Claude HUD is a Claude Code plugin that solves all three problems. It displays a multi-line statusline directly in your terminal that updates every ~300ms.

Here’s what it looks like:

[Opus | Max] │ my-project git:(main*)
Context █████░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

Installation

Install Claude HUD via npm:

npm install -g @anthropic-ai/claude-hud

Or add it to your project:

npm install @anthropic-ai/claude-hud --save-dev

After installation, restart Claude Code. The HUD appears automatically below your input field.

What Claude HUD Shows

The HUD displays six key metrics:

1. Context Window Usage

A color-coded progress bar shows your context consumption:

Context ████████░░ 65%

Green means plenty of room. Yellow means you’re getting full. Red means you’re near the limit. This helps me decide when to summarize context or start a fresh session.

2. Rate Limit Tracking

For Pro, Max, and Team subscribers:

Usage ████░░░░░░ 35% (2h 45m / 5h)

I can see exactly how much of my 5-hour window I’ve used. No more surprise lockouts.

3. Tool Activity

Shows which tools are running:

Tools: Edit → Grep → Read (running)

I can see Claude is editing files, searching code, and reading files. When tools are running, I know Claude is working.

4. Agent Status

When using subagents:

Agent: planner (Opus) - Running for 2m 15s

I can track how long an agent has been running and which model it’s using.

5. Todo Progress

Shows your todo list completion:

Todos: 3/7 complete (43%)

I use todos for complex tasks. The HUD shows my progress without switching context.

6. Git Status

Current branch and dirty state:

git:(feature/auth*) ↑2 ↓0

The asterisk shows uncommitted changes. The arrows show ahead/behind status.

Why This Matters

Before Claude HUD, I had to guess at my session state. Now I have real data.

Scenario 1: Large Codebase Refactoring

I’m refactoring a 50-file codebase. Without the HUD, I’d hit context limits mid-task. With the HUD, I see my context at 70%. I know to wrap up before hitting the limit.

Scenario 2: Rate Limit Management

I have 1 hour left in my 5-hour window. I prioritize critical tasks instead of exploratory coding. The HUD helps me budget my AI time.

Scenario 3: Long-Running Agents

I start a planner agent for a complex feature. The HUD shows it’s been running for 5 minutes. I know it’s still working, not stuck.

Configuration Options

Claude HUD supports customization through a config file:

{
  "layout": {
    "lines": 2,
    "showGit": true,
    "showTodos": true,
    "showAgents": true
  },
  "display": {
    "updateInterval": 300,
    "colorScheme": "auto"
  }
}

Key settings:

lines: Number of lines to display (1-3)
updateInterval: How often to refresh in milliseconds (default 300ms)
colorScheme: “auto”, “light”, or “dark”

How It Works

Claude HUD uses Claude Code’s native statusline API. This is important because:

No separate window: It displays directly in your terminal
No tmux required: Works in any terminal environment
Native token data: Uses actual Claude Code data, not estimates
Cross-platform: Works on macOS, Linux, and Windows

The plugin hooks into Claude Code’s internal data stream and refreshes every ~300ms with real-time metrics.

Common Issues

I ran into a few issues when first using Claude HUD.

Issue 1: HUD Not Appearing

After installation, the HUD didn’t show up. I realized I needed to restart Claude Code completely:

# Kill any running Claude Code processes
pkill -f "claude-code"

# Start fresh
claude

Issue 2: Incorrect Rate Limit Display

The rate limit showed 0% even though I had usage. This was because I wasn’t logged into my Anthropic account. Fix:

# Re-authenticate
claude auth login

Issue 3: Context Shows 0%

Context percentage showed 0% on startup. This is normal - it updates after your first message. The HUD needs at least one exchange to calculate context usage.

Use Cases

I’ve found Claude HUD most useful for:

Long Coding Sessions

When working on large features, I monitor context usage. If I hit 80%, I know to either summarize or start a new session.

Complex Multi-Step Tasks

When using agents and todos, the progress display keeps me oriented. I can see which agent is running and how many todos remain.

Rate Limit Budgeting

I track my usage throughout the day. If I’m at 75% of my 5-hour limit, I save Claude for critical tasks.

Debugging Sessions

During debugging, I watch tool activity. If Claude is stuck in a loop of Read → Grep → Read, I can intervene.

Summary

Claude HUD gives Claude Code users real-time visibility into their AI coding sessions. It displays context usage, rate limits, tool activity, agent status, todo progress, and git status - all without requiring separate windows or tmux.

Key benefits:

Prevents unexpected context limit errors
Helps manage rate limits for Pro/Max/Team users
Shows what Claude is doing in real-time
Improves session awareness

Installation is simple:

npm install -g @anthropic-ai/claude-hud

If you use Claude Code regularly, this plugin eliminates the guesswork of session management. No more surprise rate limits. No more hitting context limits mid-task.

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!