mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-05-21 15:52:37 +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>
119 lines
3.0 KiB
Markdown
119 lines
3.0 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.
|
||
|
||
[](LICENSE)
|
||
[](https://github.com/jarrodwatts/claude-hud/stargazers)
|
||
|
||
|
||
|
||
## 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
|
||
|
||
```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) |