Lightweight statusline HUD showing usage (5h/7d), context window, cost, and update alerts
npx claudepluginhub petercha90/capLightweight statusline HUD showing usage (5h/7d), context window, cost, and update alerts. Zero bloat — just the statusline.
PeterCha90Share bugs, ideas, or general feedback.
A lightweight Claude Code statusline plugin that displays
usage limits, context window, cost, and update alerts in real time.
Zero bloat. Zero dependencies. Just the statusline.
🐙 Opus 4.6 │ 🧺 73%(4h32m) │ 📅 Week: 45%(3d21h)
🗃️ 42% ctx │ 💰 $0.47 │ Update 👾
| Segment | Description |
|---|---|
🐙 Opus 4.6 | Current model (Opus=🐙, Sonnet=☄️, Haiku=💨) |
🧺 73%(4h32m) | 5-hour window utilization + time until reset |
📅 Week: 45%(3d21h) | 7-day window utilization + time until reset |
🗃️ 42% ctx | Context window usage |
💰 $0.47 | Session cost so far |
Update 👾 | Shown only when a new version is available |
Line 1 displays model, 5-hour session usage (with reset countdown), and weekly usage.
Line 2 displays context window percentage, accumulated session cost, and update alerts.
Usage percentages change color as they increase:
| Utilization | Color |
|---|---|
| < 50% | 🟢 Green |
| 50–69% | 🟡 Yellow |
| 70–84% | 🟡 Yellow (Bold) |
| >= 85% | 🔴 Red (Bold) |
Inside Claude Code:
/plugin marketplace add PeterCha90/CAP
/plugin install cap
Then apply the statusline with one of these methods:
/cap:setup inside Claude Code (recommended — works on all platforms)/reload-plugins to reload pluginsThe HUD will appear at the bottom of your terminal.
Edit scripts/usage-hud.mjs:
| Setting | Default | Description |
|---|---|---|
USAGE_TTL | 60000 (60s) | How long to cache Usage API responses. Increase to 120000 if you hit 429 rate limits. |
UPDATE_TTL | 21600000 (6h) | How often to check for new versions |
| Color thresholds | 50/70/85% | Breakpoints for green/yellow/red color transitions |
Inside Claude Code:
/cap:uninstall
Or manually:
bash ~/.claude/plugins/cap/scripts/uninstall.sh
This will:
statusLine setting (if a backup exists)Restart Claude Code after running the script.
| Problem | Solution |
|---|---|
| HUD not showing | Run /cap:setup to configure the statusline, then restart Claude Code |
HUD not showing after /reload-plugins (Windows) | /reload-plugins may not configure the statusline on Windows. Run /cap:setup instead |
Usage shows -- | OAuth token not found — verify with security find-generic-password -s "Claude Code-credentials" -w |
| Frequent 429 errors | Increase USAGE_TTL to 120000 or higher |
| Stale data | Delete cache files in ~/.claude/hud/ and restart |
cap/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest
│ └── marketplace.json # Marketplace manifest
├── commands/
│ ├── setup.md # /cap:setup
│ ├── status.md # /cap:status
│ └── uninstall.md # /cap:uninstall
├── hooks/
│ └── hooks.json # SessionStart hook
├── scripts/
│ ├── usage-hud.mjs # Main statusline script
│ ├── setup-statusline.sh # Auto-config on session start
│ └── uninstall.sh # Clean uninstall script
├── skills/
│ └── usage-hud/
│ └── SKILL.md # HUD configuration skill
├── package.json
└── LICENSE