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.

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

Step 3: Configure the statusline

/claude-hud:setup

Done! The HUD appears immediately — no restart needed.

What is Claude HUD?

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

What Each Line Shows

Session Info

[Opus | Pro] █████░░░░░ 45% | my-project git:(main) | 2 CLAUDE.md | 5h: 25% | ⏱️ 5m

• Model — Current model in use (shown first)
• Plan name — Your subscription tier (Pro, Max, Team) when usage enabled
• Context bar — Visual meter with color coding (green → yellow → red as it fills)
• Project path — Configurable 1-3 directory levels (default: 1)
• Git branch — Current branch name (configurable on/off)
• Config counts — CLAUDE.md files, rules, MCPs, and hooks loaded
• Usage limits — 5-hour rate limit percentage (opt-in, Pro/Max/Team only)
• Duration — How long the session has been running

Tool Activity

✓ TaskOutput ×2 | ✓ mcp_context7 ×1 | ✓ Glob ×1 | ✓ Skill ×1

• Running tools show a spinner with the target file
• Completed tools aggregate by type with counts

Agent Status

✓ Explore: Explore home directory structure (5s)
✓ open-source-librarian: Research React hooks patterns (2s)

• Agent type and what it's working on
• Elapsed time for each agent

Todo Progress

✓ All todos complete (5/5)

• Current task or completion status
• Progress counter (completed/total)

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)
• Parses the transcript for tool/agent activity
• Updates every ~300ms

Configuration

Customize your HUD anytime:

/claude-hud:configure

The guided flow walks you through customization — no manual editing needed:

• First time setup: Choose a preset (Full/Essential/Minimal), then fine-tune individual elements
• Customize anytime: Toggle items on/off, adjust git display style, switch layouts
• 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

You can also edit the config file directly at ~/.claude/plugins/claude-hud/config.json.

Options