mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-04-21 18:34:08 +00:00
3076489a2b
Uses time-sorted ls to find latest version - no external scripts needed. Works on all macOS/Linux versions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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
/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 |
|---|---|
| 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
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
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