Stats
Links
Categories
HUD
A Claude Code statusline plugin that shows your plan quota, real-time costs, and how much you're saving compared to using the API directly.
Full preset (expanded layout)
Minimal preset (compact layout)
Install
Inside a Claude Code session, run the following commands:
Step 1: Add the marketplace
/plugin marketplace add felipeorlando/hud
Step 2: Install the plugin
/plugin install hud
Step 3: Set up the statusline
/hud:setup
Step 4: Customize (optional)
/hud:configure
Done! The statusline appears immediately — no restart needed.
What is HUD?
HUD answers three questions you always have while using Claude Code:
| What You See | Why It Matters |
|---|---|
| Plan quota | Know when you're approaching your 5-hour rate limit before getting throttled |
| Real costs | See exactly how much you've spent today, this week, and this month in API-equivalent dollars |
| Monthly Saving | Understand how much you're saving by paying a flat subscription vs API pay-per-token pricing |
| Context usage | See how full your context window is before it gets auto-compressed |
| Tool activity | Watch Claude read, edit, and search files in real time |
| Agent tracking | See which sub-agents are running, their model, and elapsed time |
| Todo progress | Track task completion as Claude works through your checklist |
What You See
Compact layout (default)
Plan Max | Today $51 | Monthly Saving +$16
5h ━━━━━━━━━━ 14% | Context ━━━━━━━━━━ 43%
Line 1 shows plan name and cost info (pipe-separated). Line 2 shows quota bars and context usage. Stays readable on narrow terminals.
Expanded layout
Plan Max | Today $215 | Week $830 | Month $380 | Monthly Saving +$180
5h ━━━━━━━━━━ 4% | 7d ━━━━━━━━━━ 30% | Context ━━━━━━━━━━ 33%
Same two-line structure with all cost breakdowns and both quota bars enabled.
Activity lines (optional, enable via config)
◐ Read: .../file.ts | ✓ Edit ×10 | ✓ Bash ×3 ← Tools
◐ Explore [sonnet]: Exploring auth module (2m 15s) ← Agents
▸ Implement login flow (3/7) ← Todos
These appear only when there's activity to show.
Color coding
| Color | Meaning |
|---|---|
| Purple | Normal quota and context usage |
| Yellow/Amber | Warning — quota/context above 75%, or cost values |
| Red | Critical — quota/context above 90%, at limit |
| Green | Positive monthly saving, completed items |
How It Works
Claude Code invokes the statusline process every ~300ms, piping a JSON payload to stdin with model, context, and session info. The process collects data, renders ANSI output, and exits.
Claude Code ──stdin JSON──▸ hud ──stdout──▸ terminal statusline
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
Anthropic OAuth API JSONL files Transcript JSONL
(quota, plan name) (token costs) (tools, agents, todos)
Data sources
| Data | Source | Cache TTL |
|---|---|---|
| Plan name, 5h/7d quota | Anthropic OAuth API (/api/oauth/usage) | 60s |
| Token costs (today/week/month) | ~/.claude/projects/ JSONL conversation files | 30s |
| Context usage | Claude Code stdin JSON (context_window.used_percentage) | Real-time |
| Tools, agents, todos | Session transcript JSONL (incremental) | 10s |
Cost Calculation
Costs are calculated by scanning every JSONL conversation file in ~/.claude/projects/. Each message in these files contains the model used and a token usage breakdown. HUD applies the correct API pricing for each model to each message individually.
Per-model pricing
| Model | Input | Output | Cache Write | Cache Read |
|---|---|---|---|---|
| Opus 4.5 / 4.6 | $5 | $25 | $6.25 | $0.50 |
| Opus 4 / 4.1 | $15 | $75 | $18.75 | $1.50 |
| Sonnet 4 / 4.5 / 4.6 | $3 | $15 | $3.75 | $0.30 |
| Haiku 4.5 | $1 | $5 | $1.25 | $0.10 |
| Haiku 3.5 | $0.80 | $4 | $1.00 | $0.08 |
Prices per 1M tokens. Source: Anthropic pricing.
What gets counted
Each API response in the JSONL files includes:
- Input tokens — your messages + system prompt sent to the model
- Output tokens — the model's response
- Cache write tokens — tokens written to prompt cache (first time a prefix is cached)
- Cache read tokens — tokens read from prompt cache (subsequent turns)