Live token & cost heads-up display for Claude Code. Session cost with burn rate, a daily budget bar, hourly spend sparkline, context and rate-limit gauges — right in your status line. One file, zero dependencies, everything stays on your machine.

✳ Fable 5 · €1.41 €0.92/h · ↑2.2M ↓58k · cache 77% · ctx ██████▎░░░ 62%
today ██▌░░░░░░░░░░░░░ €1.41/€10 · ▁▁▂▄▁▆█ · 2 sessions · 5h █▏░░░ 24% ↻20:10

Why

Claude Code shows you nothing about spend while you work. Token HUD gives you the two numbers that actually matter, at a glance, on every message:

• this session — cost, burn rate per hour, tokens in/out, cache hit rate
• today — total across all sessions vs. your daily budget, with a bar that goes green → amber → red as you burn through it

Plus the context-window gauge and your Pro/Max 5-hour rate limit, so you see a compaction or a lockout coming before it happens.

From a calm morning to the red zone, and the --report view:

Install

As a plugin (inside Claude Code):

/plugin marketplace add Dumys/token-hud
/plugin install token-hud@token-hud

then ask Claude to "install the token hud status line" (or run the command below).

Or directly:

git clone https://github.com/Dumys/token-hud.git
cd token-hud && ./install.sh

Both paths end up doing node hud/hud.js --install, which sets statusLine in ~/.claude/settings.json (a backup of any previous status line is kept). The HUD appears on your next message.

Requires: Node.js ≥ 16 (any platform), Claude Code ≥ 2.0. Claude Code 2.1.153+ recommended (terminal-width awareness).

Configure

Set a budget and currency once:

node hud/hud.js --set dailyBudget 10
node hud/hud.js --set currency EUR

Or just tell Claude: "set my token budget to €10 a day" — the bundled /token-hud skill handles it.

Key	Default	Meaning
dailyBudget	0	daily budget in your display currency; 0 hides the bar
currency	USD	display currency (EUR, GBP, JPY, …)
autoRate	true	refresh the USD exchange rate daily (frankfurter.dev)
usdRate	0	manual exchange-rate override (0 = automatic)
lines	2	1 for a single compact line
barWidth	18	budget bar width in cells
icons	unicode	ascii if your font lacks the pretty glyphs
showModel showBurnRate showTokens showCache showContext showSpark showSessions showRateLimit	true	toggle individual segments

Config lives in ~/.claude/token-hud/config.json.

Report

node hud/hud.js --report        # today, hourly sparkline, last 7 days
node hud/hud.js --json          # same data for scripts

Or ask Claude: "how much have I spent today?"

How it works

Claude Code pipes session JSON to the status-line command on every message. Token HUD reads it, incrementally parses the session transcript for exact token counts (only new bytes each time — a few ms), and folds the numbers into per-day state under ~/.claude/token-hud/, so the budget bar covers all parallel sessions, not just the current one. Sessions crossing midnight are split correctly between days.

• Cost figures are Claude Code's own client-side estimates. On Pro/Max subscriptions they are notional — you see what the work would have cost via API, not a bill.
• Nothing is sent anywhere. The only network call is the optional daily exchange-rate fetch (--set autoRate false to disable).
• The status line renders adaptively: on a narrow terminal, lower-priority segments drop off before anything wraps.

Uninstall

./install.sh --uninstall        # or: node hud/hud.js --uninstall

State in ~/.claude/token-hud/ is kept (delete the folder if you want it gone).

License

MIT