mirror of https://github.com/jarrodwatts/claude-hud.git synced 2026-04-27 14:52:42 +00:00

Files

Jarrod Watts 8e089e5c22 update readme

2026-01-03 21:54:31 +11:00

3.1 KiB

Raw Blame History

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, zero config required.

Install

Paste this prompt into Claude Code for a guided install:

Install the "claude-hud" plugin using: https://raw.githubusercontent.com/jarrodwatts/claude-hud/main/CLAUDE.README.md

Or, if you prefer human instructions:

Step 1: Add the marketplace

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

/plugin install claude-hud@claude-hud

Step 3: Restart Claude Code

The statusline will then appear automatically below your input.

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
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

3.1 KiB Raw Blame History Unescape Escape