hud

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)