mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-05-21 15:52:37 +00:00
118 lines
3.1 KiB
Markdown
118 lines
3.1 KiB
Markdown
# 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.
|
||
|
||
[](LICENSE)
|
||
[](https://github.com/jarrodwatts/claude-hud/stargazers)
|
||
|
||
|
||
|
||
## Install
|
||
|
||
```bash
|
||
claude /plugin install github.com/jarrodwatts/claude-hud
|
||
```
|
||
|
||
> **Using Claude Code?** Paste [CLAUDE.README.md](https://raw.githubusercontent.com/jarrodwatts/claude-hud/main/CLAUDE.README.md) into your chat to have Claude install it for you.
|
||
|
||
---
|
||
|
||
## 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 |
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
```bash
|
||
git clone https://github.com/jarrodwatts/claude-hud
|
||
cd claude-hud
|
||
npm ci && npm run build
|
||
npm test
|
||
```
|
||
|
||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT — see [LICENSE](LICENSE)
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
Built with <a href="https://claude.ai/code">Claude Code</a>
|
||
</p>
|