Claude HUD

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

---

The Problem

When Claude shows "Thinking..." for minutes, you're flying blind. Is it stuck? Making progress? About to hit context limits?

The Solution

Claude HUD gives you X-ray vision into Claude's work:

What You See	Why It Matters
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

---

Quick Start

claude /plugin install github.com/jarrodwatts/claude-hud

That's it. Start Claude Code — the statusline appears automatically.

---

What Each Line Shows

Session Info

[Opus 4.5] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | 6 hooks | ⏱️ 1m

• Model — Current model in use
• Context bar — Visual meter with color coding (green → yellow → red as it fills)
• Config counts — Rules, MCPs, and hooks loaded
• 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
• Zero configuration required

---

Requirements

• Claude Code v1.0.80+
• Node.js 18+ or Bun

---

Development

git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud
npm ci && npm run build
npm test

See CONTRIBUTING.md for guidelines.

---

License

MIT — see LICENSE

---

Built with Claude Code