How Claude HUD Turns Claude Code into a Transparent Dashboard

Installation (3 commands)

# Step 1: Add the plugin marketplace
/plugin marketplace add jarrodwatts/claude-hud

# Step 2: Install the plugin
/plugin install claude-hud

# Step 3: Restart Claude Code
claude

Linux users: If you encounter EXDEV: cross-device link not permitted, run mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude before reinstalling.

Default HUD layout

The HUD displays two concise lines:

Identity line – model, plan, project path, Git branch (an asterisk * indicates uncommitted changes).

Resource line – context usage (color‑coded) and API quota usage.

Advanced customization

Enable or disable individual elements such as tools, agents, todos, project path, Git status, token breakdown, output speed, usage, session duration, etc.

Choose from three preset templates (Full, Essential, Minimal) to control the amount of information shown.

Adjust the depth of the displayed project path by editing ~/.claude/plugins/claude-hud/config.json and setting "pathLevels": 1‑3.

Customize colors by editing the colors object in the same config file. Named colors (e.g., green, brightMagenta) and hexadecimal values (e.g., #FF6600) are supported.

How Claude HUD works

Claude Code → stdin JSON → claude-hud → stdout → terminal display
               ↘ transcript JSONL (tools/agents/todos)

Key technical points:

Direct token data from Claude Code (no estimation), supporting up to 1 M context tokens.

Real‑time parsing (~300 ms intervals) of the transcript file to extract tool, agent, and todo activity.

Zero‑dependency architecture – works in any terminal without tmux or separate windows.

Practical scenarios

Context explosion warning: HUD shows Context ██████████ 85%, prompting you to trim the context before a crash.

Agent runtime tracking: Displays elapsed time, e.g., explore [sonnet]: Analyzing codebase (3m 45s).

Quota monitoring: Shows usage bars such as Usage ██████████ 90% (4h 30m / 5h) to avoid hitting limits.

Multi‑project switching: Lists active Claude Code windows with their project paths, helping you keep track of several sessions.

Common issues & solutions

Configuration not applied – verify JSON syntax or delete the config file and restart.

Git status missing – ensure the current directory is a Git repository and gitStatus.enabled is set to true.

Quota not shown – requires Pro/Max/Team subscription and OAuth login (API key alone is insufficient).

HUD not appearing – fully exit Claude Code and relaunch.

Repository

https://github.com/jarrodwatts/claude-hud