headroom-stats — Headroom LLM token-savings dashboard (CLI + VS Code extension)

Visualize your Headroom token savings in a rich, information-dense dashboard — available both as a terminal CLI and a VS Code extension. A far more detailed alternative to headroom perf: per-project, per-model, per-agent, prefix-cache and RTK savings, trends over time, and cost in real dollars.

headroom-stats turns the raw /stats data from the Headroom AI context-compression proxy into an at-a-glance view of how many tokens — and how much money — you save when running Claude Code and other LLM agents. Track token-usage reduction, compression ratio, prefix-cache savings, and per-project / per-model / per-agent breakdowns over time, live.

Two ways to use it:

• 🖥️ Terminal CLI (headroom-stats) — pure-Python, zero-dependency dashboard for macOS, Linux, and Windows. (this repo's main script)
• 🧩 VS Code extension — a live, graphical dashboard + status-bar widget inside your editor. Tabs for Today, All Time, Sessions, Agents, Models, Projects, Cache and Layers, with filters and an in-app settings page. See vscode-extension/.

Keywords: Headroom · LLM token savings · token usage optimization · context compression · Claude Code · AI agent cost reduction · prefix cache · RTK · savings dashboard · VS Code extension.

---

What is this?

headroom-stats is a dashboard that visualises everything Headroom tracks about your LLM token savings in one colourful, information-dense view.
It replaces headroom perf with a far more visual and detailed overview:

Feature	headroom perf	headroom-stats
Lifetime savings summary	✓	✓
Per-project breakdown	—	✓
By Command table (RTK)	—	✓
Daily breakdown (15 days)	—	✓
Weekly summary	—	✓
Monthly summary	—	✓
Savings-over-time bar chart	—	✓
Session vs lifetime view	—	✓
Active config flags	—	✓
Auto-refresh watch mode	—	✓

---

Requirements

• Python 3.10+
• Headroom proxy running locally (hr-proxy start, or just run claude-hr)
• Optional: RTK installed for the By Command section

Runs on macOS, Linux, and Windows — pure Python standard library, no dependencies. On Windows 10+ ANSI colours are enabled automatically; the RTK database is located per-OS (%APPDATA%\rtk, ~/Library/Application Support/rtk, or $XDG_DATA_HOME/rtk), overridable with RTK_DB.

---

Installation

macOS / Linux

# Copy to somewhere on your PATH
cp headroom-stats claude-hr hr-proxy hr-reap ~/.local/bin/
chmod +x ~/.local/bin/{headroom-stats,claude-hr,hr-proxy,hr-reap}

Windows — copy the scripts somewhere on your PATH and run them with Python (python headroom-stats), or create .cmd shims. Environment overrides: HEADROOM_PORT, RTK_DB, HEADROOM_STATS_REPO.

---

Usage

# One-shot render (default: last 15 days)
headroom-stats

# Show more/fewer days in Daily Breakdown
headroom-stats --days=30

# Live auto-refresh every 5 seconds
headroom-stats --watch

# Custom refresh interval
headroom-stats --watch=10

---

Sections

Overview

Four summary cards: tokens saved, cost saved, total requests, and proxy status.

This Session

Current session metrics including compression ratio, average savings %, and session start time.

Savings Over Time

Bar chart of token savings per interval, trimmed to start from the first actual activity date — no dead whitespace for periods before you started using Headroom.

By Command (RTK)

Table ranked by total tokens saved, showing count, saved tokens, average savings %, average exec time, and an impact bar. Requires RTK to be installed.

Per-Project Breakdown

Token and cost savings broken down by project, with a share bar.

Daily Breakdown

Last 15 days of daily savings with dual sparkline bars. Configurable with --days=N.

Weekly Breakdown

All available data aggregated by ISO week.

Monthly Breakdown

All available data aggregated by calendar month.

Active Config

Key Headroom configuration flags including Auto Memory, Force Kompress, Accuracy Guard, and compression settings — with real ON/OFF state detection.

---

🧩 VS Code Extension

Prefer a graphical dashboard inside your editor? The Headroom Stats VS Code extension brings the same token-savings data to VS Code:

• A status-bar widget showing live tokens spent / saved / $ saved, color-coded by savings %, with a rich hover popup.
• A glassmorphic dashboard with tabs — Overview, Today, All Time, Sessions, Agents, Models, Projects, Cache, Layers — plus charts, donuts, a token-flow view, and date/project/agent filters.
• Multi-proxy support (switch between every running claude-hr --port N session) and an in-app Settings page.
• Reads the Headroom proxy /stats endpoint directly with a disk fallback — no CLI required.

→ Full details, screenshots and install instructions in vscode-extension/.

---

Companion tools: claude-hr & hr-proxy

These two scripts ship in this repo. They make running Claude Code through Headroom a one-word command instead of a long incantation — and, like headroom-stats, they run on macOS, Linux, and Windows (the originals were mac/linux-only shell functions).

claude-hr — launch Claude Code through Headroom

Normally you'd start Claude behind the compression proxy with something like:

headroom wrap claude --port 8787 --no-proxy -- --dangerously-skip-permissions

claude-hr collapses that to just:

claude-hr

What it does for you:

1. Resolves a port — --port N if given, else the nearest .claude-hr-port file walking up from the current directory, else it picks a free port and saves it to your repo root. This means each project gets its own stable proxy port, so per-project savings show up correctly in the dashboard's Per-Project Breakdown.
2. Auto-starts the proxy on that port if nothing is listening yet.
3. Launches Claude wrapped by Headroom, with permissions skipped so you don't get prompted mid-session.

claude-hr                    # auto port from .claude-hr-port (or prompt once, then remembered)
claude-hr --port 9000        # force a specific proxy port
claude-hr --port 9000 chat   # extra args pass straight through to claude

With no resolvable port it falls back to Headroom's own managed proxy (--memory mode on the default port).

Auto-stop on exit: when Claude exits (including Ctrl-C), claude-hr stops that port's proxy — but only if no other client (another claude-hr session, the VS Code extension) is still connected to it. This stops orphaned proxies from piling up and eating RAM. POSIX-only (uses lsof); on Windows it no-ops.

hr-reap — reap idle proxies

Orphaned proxies from earlier sessions still hogging RAM? hr-reap kills every proxy that has no client connected, leaving the ones you're actively using untouched:

hr-reap                # kill every idle proxy
hr-reap -n             # dry-run — show what would be killed
hr-reap keep mynes     # never touch a proxy whose repo dir matches "mynes"

"In use" = some process other than the proxy holds an ESTABLISHED connection to its port. POSIX-only (pgrep/ps/lsof).

hr-proxy — proxy session manager

A tiny manager for the background Headroom proxies, tracked in ~/.headroom-proxy.tsv:

hr-proxy start [PORT]     # start a proxy (default 8787), remembers pid/port/dir
hr-proxy stop PORT|PID    # stop one
hr-proxy list             # show running sessions
hr-proxy log [PORT]       # show the log file path + last lines

claude-hr calls hr-proxy's start logic under the hood, so you rarely need it directly — but hr-proxy list / stop are handy for cleaning up proxies across projects.

Why they help: together they turn "remember the port, start the proxy, wrap Claude, skip permissions" into claude-hr, and keep each project pinned to its own port so headroom-stats can attribute savings per-project.

---

Related

• Headroom — the AI context compression proxy this tool reads from
• RTK — CLI token filtering tool whose command-level data powers the By Command section