Overview
It is a HUD plugin that uses Claude Code's native statusline API. It works in all terminals without a separate tmux or external tool. It displays context usage, tool activity, agent status, and todo progress in the statusline in real time.
Features
The HUD displays the following information in the statusline:
Line 1 (basic information):
- Model name in use
- Plan name
- Project path
- Git branch
Line 2 (Context usage):
- Context bar: green -> yellow -> red color transition based on usage
- Display usage rate limits
Optional display items:
- Tools activity (currently running tools)
- Agent status (active agent tracking)
- Todo progress (to-do progress rate)
Installation
Step 1: Add claude-hud to Marketplace
/plugin marketplace add jarrodwatts/claude-hud
Step 2: Install the plugin
/plugin install claude-hud
Step 3: Statusline setup
/claude-hud:setup
The setup command automatically completes the statusline configuration.
Claude Code must be restarted after installation.
Configuration
Customization
/claude-hud:configure
Presets
| Preset | Description |
|---|---|
| Full | Display all items (context, tools, agents, todo) |
| Essential | Display only activity status + git information |
| Minimal | Display only core information (model, context bar) |
Layout
| Layout | Description |
|---|---|
| Expanded | Multiline layout (information distributed across multiple lines) |
| Compact | Single-line layout (compactly displayed on one line) |
Config file
Config file location: ~/.claude/plugins/claude-hud/config.json
Troubleshooting
| Symptom | Solution |
|---|---|
| HUD not displayed | Restart Claude Code |
| Linux EXDEV error | mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude |
| Ghost install (installed but not working) | /claude-hud:setup refer to Step 0 of |
| Runtime detection failure | Check that Node.js 18+ or Bun is installed |
Requirements
- Claude Code v1.0.80+
- Node.js 18+ or Bun