Skip to main content
Claude Code sessions give you no built-in visibility into what’s happening under the hood. You can’t easily see how full your context window is, which tools are running, whether subagents are active, or how your rate limits are tracking — until it’s too late. Claude HUD fixes that by adding a persistent, real-time statusline directly in your terminal.
Claude HUD uses Claude Code’s native statusline API — no separate window, no tmux required. It works in any terminal.

​
What it looks like

By default, Claude HUD shows two lines below your input: 
[Opus | Max] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
  • Line 1 — Model name, plan (or Bedrock), project path, git branch
  • Line 2 — Context bar (green → yellow → red) and usage rate limits
Optional lines can be enabled via /claude-hud:configure: 
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← Tools activity
◐ explore [haiku]: Finding auth code (2m 15s)    ← Agent status
▸ Fix authentication bug (2/5)                   ← Todo progress

​
Features

​
Context bar

See exactly how full your context window is before it becomes a problem. The bar changes color as you approach limits:
UsageColor
Below 70%Green
70–85%Yellow
Above 85%Red — token breakdown shown
Token counts come directly from Claude Code’s native stdin data — not estimated.

​
Tool activity

Watch Claude read, edit, and search files as it happens. When enabled, the tools line shows running and recently completed tools in real time: 
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
This line is hidden by default. Enable it with display.showTools: true.

​
Agent tracking

See which subagents are running, which model they’re using, and what they’re doing — including how long they’ve been running: 
◐ explore [haiku]: Finding auth code (2m 15s)
Enable with display.showAgents: true.

​
Todo progress

Track task completion in real time as Claude works through a todo list: 
▸ Fix authentication bug (2/5)
Enable with display.showTodos: true.

​
Usage limits

For Claude Pro, Max, and Team subscribers, Claude HUD shows your rate limit consumption alongside the context bar: 
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)
The 7-day window appears automatically when usage exceeds the configured threshold (default: 80%). Usage data is fetched from the Anthropic OAuth API and cached to minimize overhead.
Usage display requires a Claude Pro, Max, or Team subscription. It is not available for API key users or AWS Bedrock.

​
Git status

Line 1 always shows your current branch. You can optionally enable additional git indicators: 
[Opus] │ my-project git:(main* !3 +1 ?2)
  • * — uncommitted changes
  • ↑N ↓N — commits ahead/behind remote
  • ! modified, + added, ✘ deleted, ? untracked

​
How it works

Claude HUD is invoked by Claude Code’s statusline API approximately every 300ms: 
Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
           ↘ transcript JSONL (tools, agents, todos)
Each invocation receives a JSON payload with the current model, context window, and token counts — native accurate data, not estimates. Claude HUD also parses the session transcript to extract tool calls, agent activity, and todo state.

​
Requirements

  • Claude Code v1.0.80+
  • Node.js 18+ or Bun
Bun is preferred over Node.js for performance when both are installed. The setup command detects and uses Bun automatically.

​
Next steps

Quickstart

Install the plugin and get your HUD running in under two minutes.

Configuration

Customize your layout, toggle features, and adjust colors and thresholds.

How it works

Understand the data sources and architecture behind Claude HUD.

Troubleshooting

Fix common issues with the HUD not appearing or usage not displaying.

Build docs developers (and LLMs) love

Get started for freeTalk to us