claude-hud

Claude HUD

A Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.

🌐 English | 中文文档

Install

Inside a Claude Code instance, run the following commands:

Step 1: Add the marketplace

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

EXDEV: cross-device link not permitted

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

/plugin install claude-hud

After that, reload plugins:

/reload-plugins

Step 3: Configure the statusline

/claude-hud:setup

winget install OpenJS.NodeJS.LTS

Done! Restart Claude Code to load the new statusLine config, then the HUD will appear.

On Windows, make that a full Claude Code restart after setup writes the new statusLine config.

What is Claude HUD?

Claude HUD gives you better insights into what's happening in your Claude Code session.

What You See

Default (2 lines)

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

• Line 1 — Model, provider label when positively identified (for example Bedrock, Vertex), project path, git branch
• Line 2 — Context bar (green → yellow → red) and usage rate limits

Optional lines (enable 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

How It Works

Claude HUD uses Claude Code's native statusline API — no separate window, no tmux required, works in any terminal.

Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
           ↘ transcript JSONL (tools, agents, todos)

Key features:

• Native token data from Claude Code (not estimated)
• Scales with Claude Code's reported context window size, including newer 1M-context sessions
• Parses the transcript for tool/agent activity
• Updates every ~300ms

Configuration

Customize your HUD anytime:

/claude-hud:configure

The guided flow handles layout, language, and common display toggles. Advanced overrides such as custom colors and thresholds are preserved there, but you set them by editing the config file directly:

• First time setup: Choose a preset (Full/Essential/Minimal), pick a label language, then fine-tune individual elements
• Customize anytime: Toggle items on/off, adjust git display style, switch layouts, or change label language
• Preview before saving: See exactly how your HUD will look before committing changes

Presets

After choosing a preset, you can turn individual elements on or off.

Manual Configuration

Edit ~/.claude/plugins/claude-hud/config.json directly for advanced settings such as colors.*, pathLevels, maxWidth, threshold overrides, display.timeFormat, and display.promptCacheTtlSeconds. Running /claude-hud:configure preserves those manual settings while still letting you change language, layout, and the common guided toggles.