AI Tool Atlas
Usage tracker

Claude HUD

Claude Code statusline plugin that shows context usage, the five-hour and seven-day limits, active tools and todo progress under the input.

Author
Jarrod Watts
Works with
Claude Code
License
MIT
Documented
Oct 28, 2026
Repository ↗ Official docs ↗

What Claude HUD is

Claude HUD is a plugin for Claude Code that draws a status line below the input: context usage, rate limits, active tools, running agents and todo progress. Usage appears whenever Claude Code sends subscriber rate limits, so it stays hidden for API-key, Bedrock and Vertex sessions. The seven-day window appears once it passes a configurable threshold (80% by default).

What it does

How Claude HUD plugs in: which agents run it and what it addsRUNS INYour agentClaude Codeone host documentedTRACKERClaude HUDShows how much of a plan's usage…4 install steps1 permission notelicense: MITWHAT IT ADDSWhat it doesContext window usage on every turnFive-hour window, and the seven-d…Per-model weekly windows, pace co…Active tools, running agents and…agent → extension → new capability · from the official repository or docs
Where Claude HUD runs and what it adds, from its documentation
  • Context window usage on every turn
  • Five-hour window, and the seven-day window above display.sevenDayThreshold
  • Per-model weekly windows, pace colouring, reset countdown or wall-clock time
  • Active tools, running agents and todo progress
  • Can read or write usage snapshots to a local JSON file

When to use it

Good fit

  • You use Claude Code on a Pro, Max or Team plan and want the limits visible without leaving the terminal

Not for

  • API-key, Bedrock or Vertex sessions, where no subscriber rate limits are sent

How to install Claude HUD

You need: Claude Code v2.1.260 or later; Node.js 18+ or Bun (macOS, Linux); Node.js 18+ on Windows

Install in one click

Paste the copied command into the Claude Code terminal and confirm the prompt.

  1. In Claude Code: /plugin marketplace add jarrodwatts/claude-hud
  2. /plugin install claude-hud
  3. /reload-plugins
  4. /claude-hud:setup
Configuration example (from the official docs)
{
  "display": {
    "showUsage": true,
    "usageValue": "percent",
    "sevenDayThreshold": 80,
    "usagePace": false
  }
}

Permissions and security

What it can access

  • Reads rate limits that Claude Code passes to statusline plugins

Review the source before granting an agent access to credentials or production systems. We document what the maintainers state; we do not audit code.

Limitations

  • Usage display needs a subscription session; nothing is shown for API keys

Tools it extends

Frequently asked questions

Why does Claude HUD show no usage?

Usage appears only when Claude Code sends subscriber rate limits. API-key, Bedrock and Vertex sessions do not send them, so the usage line stays hidden.

How do I install Claude HUD from the terminal?

claude plugin marketplace add jarrodwatts/claude-hud, then claude plugin install claude-hud@claude-hud, then /reload-plugins and /claude-hud:setup inside a session.

When does the seven-day window appear?

Once usage passes display.sevenDayThreshold, 80 percent by default; set display.showUsage to false to hide usage entirely.

Sources and gaps