Headroom Stats — VS Code Extension

A fancy, live dashboard + status-bar widget for Headroom token savings — every saving Headroom tracks, in a graphical UI, right inside VS Code.

Companion to the headroom-stats terminal dashboard. Same data, now with charts, donuts, tabs, and a status-bar widget that updates while you work.

Overview — active session, token flow, savings trend, and top agents / models / projects at a glance (shown in cumulative All proxies mode):

Status Bar Widget — spent, tokens saved cost, savings %, project breakdown, active sessions

Features

📊 Live dashboard (Headroom: Open Savings Dashboard)

A dense, glassmorphic dashboard with a persistent KPI hero (lifetime tokens saved, $ saved, prefix-cache $, requests, avg savings %) and tabs:

Data model: lifetime totals, the active session, the full history (thousands of points) and per-project breakdown come from the shared on-disk store (proxy_savings.json), so savings are always fully visible regardless of which proxy you pick. Live agents / models / cache / layers / subscription windows come from the selected proxy's /stats. (Session-level filtering isn't offered because Headroom keeps only the current session's detail, not a per-session archive.)

Note on Branches / Workflows: Headroom's /stats API tracks savings by project, model, agent, and layer — but not by git branch or workflow. So instead of empty "Branches"/"Workflows" tabs, this extension ships the two data-rich Headroom-native tabs Cache and Layers. If you'd like literal Branches/Workflows tabs (populated from Claude Code's own session logs), that's a straightforward addition — open an issue.

🚀 Status-bar widget

A compact, always-visible widget (default: spent 2.8M · saved 19.0K · $0.10) that:

• Refreshes on an interval (default 10s)
• Color-codes by this session's savings % (green / yellow / red, thresholds configurable)
• Shows a rich hover popup (session, lifetime, top projects, cache — all configurable)
• Click → opens the dashboard

Everything about it is user-configurable in Settings (Headroom: Open Settings, or the ⚙ button in the dashboard).

Multiple proxies

Run several claude-hr --port <N> sessions and each one shows up as a separate proxy. The extension:

• Discovers every running proxy via ~/.headroom/.beacon_lock_*.
• Shows a proxy switcher at the top of the dashboard (e.g. 6 proxies → :8787 · :8888 · :9999 …), each pill labelled with its tokens saved and savings %. Click to switch which proxy the whole dashboard reflects.
• Marks the active proxy in the status-bar hover popup, which lists all proxies with per-proxy totals.
• Remembers your selected proxy (per workspace); if it goes away, it falls back to the most-active one.

Data source — no CLI required

The extension is standalone. It does not need the headroom-stats CLI (or any of the claude-hr / hr-proxy scripts) installed. It reads Headroom directly:

1. http://localhost:<port>/stats — the live Headroom proxy (rich, real-time).
2. ~/.headroom/proxy_savings.json — disk fallback when no proxy is up (lifetime + session + projects + history stay visible).

What it does need is Headroom itself running at least once, so there is data to show — either a live proxy on a port, or the saved proxy_savings.json on disk. With neither, the dashboard shows an empty state explaining how to start one.

No proxy running? Start Headroom (hr-proxy start, or just run claude-hr), then click Refresh.

Settings

Status-bar metric options: sessionSpent, sessionSaved, sessionCost, sessionPercent, lifetimeSaved, lifetimeCost, cacheSaved, requests, todaySaved, todayCost.

Develop / run locally

cd vscode-extension
npm install
npm run compile          # or: npm run watch

Then press F5 in VS Code (Run → Start Debugging) to launch an Extension Development Host with the extension loaded. The status-bar widget appears immediately; run Headroom: Open Savings Dashboard from the command palette.

To preview the dashboard UI in a plain browser (for tweaking styles or capturing screenshots) — no VS Code needed:

npm run preview          # builds from your live proxies + disk, serves it, and opens your browser

This starts a small local server on http://localhost:5599 (override with PREVIEW_PORT) and opens it automatically. It is not a Headroom proxy port — don't open localhost:8787 (that's the proxy itself). Press Ctrl-C to stop.

Install from a .vsix

npx @vscode/vsce package --no-dependencies    # → headroom-stats-<version>.vsix
code --install-extension headroom-stats-<version>.vsix

Or in VS Code: Extensions → ⋯ → Install from VSIX…

_{🚀 Headroom Stats · developed by @FXerkan · code more, worry less}