headroom-usage-indicator

A tiny status-line indicator for Claude Code that shows — at a glance, at the bottom of your screen — whether the headroom context-compression MCP is actually being used in your current session, and how many tokens it has saved you.

No more wondering "did I remember to compress that huge file, or did I just burn context?" — the indicator tells you, honestly, in real time.

Quickstart (two commands and the doctor)

Type these into the Claude Code prompt:

/plugin marketplace add Ship-Wright/headroom-plugin
/plugin install headroom-usage-indicator@headroom-tools

Then ask Claude, in plain English: "run the headroom doctor" (or invoke it directly: /headroom-usage-indicator:doctor). It checks everything — jq, the headroom compression engine, the MCP server, the hooks, the status line — and, with your consent, fixes whatever is missing, including the one thing a plugin can't do by itself: writing the statusLine entry into your ~/.claude/settings.json.

That's it. As of v2.5 the plugin is self-contained: the hooks (Dangi and the hcat gate) register themselves the moment the plugin is enabled, hcat is already on Claude's Bash PATH, and the headroom MCP server registration comes bundled — no scripts to copy, no settings.json hook surgery. If you installed an earlier version by hand, see Migrating from a pre-v2.5 install.

Verify it works

Paste this into the Claude Code prompt:

Create a roughly 100 KB JSON file at /tmp/hr-demo.json (an array of a few thousand small objects), then show me what's in it.

You should see, in order:

the hcat gate step in — instead of raw-reading the file, Claude gets redirected to run hcat /tmp/hr-demo.json;
the output open with a receipt line like ── hcat: /tmp/hr-demo.json · 1 lines · 98.3 KB · ~25000 tok → ~7500 tok (70.0% saved) · original on disk …;
the badge at the bottom of your screen flip green within a second or two: ● headroom · ~17.5k tok · $… · 1× ….

If any of those three don't happen, ask Claude to run the headroom doctor — diagnosing exactly this is its whole job.

The badge across its three real states — red idle (big files read raw), green active (an hcat receipt just landed: tokens and $ saved), grey decayed (quiet 60s, keeps the tally and flags what was missed).

The gauge and the engine

This plugin does not compress anything by itself — the actual compression is done by headroom, a local Python engine (→ https://github.com/headroomlabs-ai/headroom). Think of it like a fuel gauge: headroom is the engine, this plugin is the gauge (plus, since v2.3, a hand that reaches for the fuel-saver button for you).

The good news: you no longer have to plumb the engine in yourself. The plugin bundles the MCP server registration (its tools appear as mcp__headroom__headroom_compress and friends), and if the engine itself is missing, the doctor offers to bootstrap it into ~/.headroom-venv. If headroom is absent and you decline, everything stays politely silent — the badge sits at "idle", the gate lets Reads through — nothing breaks.

What it does

Every second, it looks at what your Claude session has actually done and updates a small badge in your status line. It reads the real session activity (not guesses), so it can't be fooled — just looking at headroom's stats does not make it say "active"; only a real compression does.

What it shows

Badge	Colour	Meaning
`○ headroom idle (not compressing yet)` — or `○ headroom idle · 4 big blobs uncompressed`	🔴 red	headroom hasn't compressed anything yet this session; the count appears when large tool outputs are going uncompressed
`● headroom · ~2.4k tok · $0.01 · 3× \| $1.83 all-time 😴 dangi`	🟢 green	a compression just happened — tokens saved, money saved, how many times, and your all-time total
`○ headroom idle · ~2.4k tok · $0.01 · 3× · 2 missed \| $1.83 all-time 🤖 dangi: 2!`	⚪ grey	quiet for 60s — dims, but keeps the totals; `· N missed` counts big results beyond what you've compressed

The token count is the running total for the whole session (it adds up every compression).
It resets to red when you start a brand-new Claude session.

How the money number works