mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-04-30 00:42:43 +00:00
345c9d6486
feat: display project folder name in session line - Add project folder name with 📁 emoji at start of session line - Use path.basename() for cross-platform compatibility - Add tests for POSIX/Windows paths and edge cases Co-authored-by: Tsopic <39419095+Tsopic@users.noreply.github.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 |
|---|---|
| Project name | Always know which project you're working in |
| 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
📁 my-project | [Opus 4.5] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | 6 hooks | ⏱️ 1m
- Project — Current working directory folder name
- 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