mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-05-02 02:22:39 +00:00
e9b0e9f680
- Add ~/.claude.json user-scope MCP support - Add .mcp.json project MCP support - Add .claude/settings.local.json support - Add CLAUDE.local.md and .claude/CLAUDE.md detection - Deduplicate MCPs that appear in multiple files Locations now covered: - User: ~/.claude/CLAUDE.md, ~/.claude/rules/, ~/.claude/settings.json, ~/.claude.json - Project: CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md, .claude/rules/, .mcp.json - Project settings: .claude/settings.json, .claude/settings.local.json 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# Claude HUD
|
||
|
||
[](LICENSE)
|
||
|
||
Real-time statusline HUD for Claude Code. See context usage, tool activity, agent status, and todo progress directly in your terminal.
|
||
|
||
```
|
||
[Opus] ████████░░ 45% | 📋 3 rules | 🔌 5 MCPs | ⏱️ 12m
|
||
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
|
||
◐ explore [haiku]: Finding auth code (2m 15s)
|
||
▸ Fix authentication bug (2/5)
|
||
```
|
||
|
||
## Why?
|
||
|
||
When Claude shows "Thinking..." for minutes, you have no visibility into what's happening. Claude HUD gives you **X-ray vision**:
|
||
|
||
- **Context health** — See exactly how full your context window is (native, accurate data)
|
||
- **Tool activity** — Watch Claude read, edit, and search files in real-time
|
||
- **Agent tracking** — See which subagents are running and what they're doing
|
||
- **Todo progress** — Track task completion as Claude works
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
claude /plugin install github.com/jarrodwatts/claude-hud
|
||
```
|
||
|
||
That's it. Start Claude Code as usual — the statusline appears automatically.
|
||
|
||
## What You See
|
||
|
||
### Line 1: Session Info
|
||
```
|
||
[Opus] ████████░░ 45% | 📋 3 rules | 🔌 5 MCPs | ⏱️ 12m
|
||
```
|
||
- **Model** — Current model (Opus, Sonnet, Haiku)
|
||
- **Context bar** — Visual progress with color coding:
|
||
- 🟢 Green: <70% (healthy)
|
||
- 🟡 Yellow: 70-85% (getting full)
|
||
- 🔴 Red: >85% (warning) — shows token breakdown
|
||
- ⚠️ COMPACT: >95% (critical)
|
||
- **Rules count** — How many CLAUDE.md files loaded
|
||
- **MCP count** — Connected MCP servers
|
||
- **Hooks count** — Number of configured hooks (from settings)
|
||
- **Duration** — Session time
|
||
|
||
### Line 2: Tool Activity
|
||
```
|
||
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
|
||
```
|
||
- **Running tools** with ◐ spinner and target file
|
||
- **Completed tools** aggregated by type with counts
|
||
|
||
### Line 3: Agent Status (when active)
|
||
```
|
||
◐ explore [haiku]: Finding auth code (2m 15s)
|
||
```
|
||
- **Agent type** and model
|
||
- **Description** of what it's doing
|
||
- **Elapsed time**
|
||
|
||
### Line 4: Todo Progress (when todos exist)
|
||
```
|
||
▸ Fix authentication bug (2/5)
|
||
```
|
||
- **Current task** being worked on
|
||
- **Progress** (completed/total)
|
||
|
||
## How It Works
|
||
|
||
Claude HUD uses Claude Code's **statusline API** — a multi-line display that updates every ~300ms.
|
||
|
||
Unlike other approaches, Claude HUD:
|
||
- **No separate window** — Displays inline in your terminal
|
||
- **No hooks required** — Parses the transcript directly (hooks are optional and only counted)
|
||
- **Native data** — Gets accurate token/context info from Claude Code
|
||
- **Works everywhere** — Any terminal, not just tmux/iTerm
|
||
|
||
### Architecture
|
||
|
||
```
|
||
Claude Code → stdin JSON (model, tokens, context)
|
||
→ transcript JSONL (tools, agents, todos)
|
||
→ claude-hud renders 4 lines
|
||
→ Claude Code displays them
|
||
```
|
||
|
||
## Requirements
|
||
|
||
- Claude Code v1.0.80+
|
||
- Node.js 18+ or Bun
|
||
|
||
## Configuration
|
||
|
||
Claude HUD works with zero configuration. Optionally customize via `~/.claude/hud/config.json`:
|
||
|
||
```json
|
||
{
|
||
"showRules": true,
|
||
"showMcps": true,
|
||
"showDuration": true,
|
||
"contextWarningThreshold": 85,
|
||
"contextCriticalThreshold": 95
|
||
}
|
||
```
|
||
|
||
## Development
|
||
|
||
```bash
|
||
git clone https://github.com/jarrodwatts/claude-hud
|
||
cd claude-hud
|
||
|
||
# Install & build
|
||
bun install
|
||
bun run build
|
||
|
||
# Test with sample data
|
||
echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000}}' | node dist/index.js
|
||
```
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
See `TESTING.md` for the full testing strategy and contribution expectations.
|
||
|
||
## License
|
||
|
||
MIT
|
||
|
||
## Credits
|
||
|
||
Built with [Claude Code](https://claude.ai/code).
|
||
|
||
---
|
||
|
||
**v2.0** — Complete rewrite from split-pane TUI to inline statusline. [See v1 for the original split-pane version](https://github.com/jarrodwatts/claude-hud/tree/v1.0.0-split-pane).
|