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

<details> <summary><strong>⚠️ Linux users: Click here first</strong></summary>

On Linux, /tmp is often a separate filesystem (tmpfs), which causes plugin installation to fail with:

EXDEV: cross-device link not permitted

Fix: Set TMPDIR before installing:

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

Then run the install command below in that session. This is a Claude Code platform limitation.

</details>

/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 You See | Why It Matters | |--------------|----------------| | Project path | Know which project you're in (configurable 1-3 directory levels) | | Context health | Know exactly how full your context window is before it's too late | | Tool activity | Watch Claude read, edit, and search files as it happens | | Agent tracking | See which subagents are running and what they're doing | | Todo progress | Track task completion in real-time |

What Each Line Shows

The HUD is rendered as a single statusline; the sections below are shown inline, separated by |.

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, or Bedrock when using AWS Bedrock models
• Context bar — Visual meter with color coding (green → yellow → red as it fills), with percent or tokens based on config
• 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; hidden for Bedrock)
• 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 st...