Make Headroom compression visible.
A live terminal dashboard for teams that want proof their agent context is being recovered, compressed, and reused.
LLM agents burn context quietly. Headroom compresses that context, but the work is
mostly invisible unless you read proxy logs. headroom-meter turns those logs
into an executive-readable dashboard: token savings, compression spikes, cache
hits, frame reduction, and active transforms, all updating live in your terminal.
It is the hybrid-car regen meter for AI context.
The new speedometer shows the latest completed request in real time. The odometer beside it shows the cumulative tokens recovered during the session.
Example measurement from one local Codex + Headroom session on June 24, 2026:
| Signal | Reading |
|---|---|
| Completed requests | 196 |
| Input tokens before Headroom | 14,180,388 |
| Input tokens after Headroom | 13,845,926 |
| Tokens saved | 334,462 |
| Average saved per request | 1,706 |
| Peak single-request save | 65,187 |
| Average cache hit rate | 95.2% |
| WebSocket frame tokens saved | 154,575 |
| Frame byte reduction | 6.07% |
These numbers are a field reading from a real local proxy.log, not a universal
benchmark. Your savings depend on workflow, model, context shape, and Headroom
configuration.
- See ROI while work is happening. A live meter makes compression tangible.
- Get an instant current reading. The speedometer answers, "how much did the last request save?"
- Debug context-heavy agent sessions. Spikes and flatlines are visible at a glance.
- Explain Headroom to non-operators. The dashboard is easier to understand than
tok_before=.... - Keep the stack lightweight. One Python script, no packages, no daemon, no telemetry.
Fast install from GitHub:
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/RonnieTheTester/headroom-meter/main/bin/headroom-meter -o ~/.local/bin/headroom-meter
chmod +x ~/.local/bin/headroom-meterOr clone it:
git clone https://github.com/RonnieTheTester/headroom-meter.git
cd headroom-meter
./install.shMake sure ~/.local/bin is on your PATH.
Start the live dashboard:
headroom-meterLive mode uses your terminal's alternate screen, so it stays pinned in place instead of filling your scrollback.
Start counting from zero instead of aggregating the existing log:
headroom-meter --live-onlyPrint one snapshot and exit:
headroom-meter --onceMake the bars more sensitive:
headroom-meter --scale 10Force color output, useful for terminal recordings:
headroom-meter --color alwaysUse ASCII-only graphs:
headroom-meter --asciiDisable alternate-screen mode if you explicitly want scrollback output:
headroom-meter --no-alt-screenUse a custom Headroom log path:
headroom-meter --log /path/to/proxy.logCheck the installed version:
headroom-meter --versionExplain the dashboard labels:
headroom-meter /helpor:
headroom-meter --explainBy default, headroom-meter tails:
~/.headroom/logs/proxy.log
It parses Headroom fields such as:
tok_before=60229 tok_after=57678 tok_saved=2551 cache_hit_pct=98
Then it turns them into:
- token regen gauge
- live savings speedometer
- cumulative token odometer
- recent request pulse graph
- frame compression graph
- cache battery
- optimization timing
- active transform list
- TOIN pattern/compression activity
The script is read-only. It does not modify Headroom config or send data anywhere.
| Label | What it means |
|---|---|
| Live Savings Speedometer | The current savings level for the latest completed request. This is the fastest way to tell whether Headroom is working right now. |
| NOW | The latest request's savings percentage: tok_saved / tok_before. |
| Odometer | Cumulative tokens saved across the log or current --live-only session. |
| Token Regen | Aggregate compression rate across completed requests. Think of this as overall recovered context. |
| Recent Request Pulses | A sparkline of recent request savings. Taller pulses mean stronger recent compression spikes. |
| Frame Compression | WebSocket frame byte reduction. This is transport/frame-level compression, separate from request-level token savings. |
| Saved Tokens | Total tok_saved observed by the meter. |
| Last Request | Tokens saved by the most recently completed request. |
| Requests | Completed request count plus average tokens saved per request. |
| Cache Battery | Weighted average cache_hit_pct. Higher means more context is being reused from cache. |
| Optimize Time | Average time Headroom spent optimizing/compressing before forwarding upstream. |
| Transforms | Headroom transformations seen on the latest request, such as text, smart_crusher, kompress, or log. |
| TOIN | Headroom token/object indexing activity: patterns, compressions, retrievals, and retrieval rate. |
headroom-meter does not perform compression. It instruments Headroom's
compression logs and makes the effect legible.
The underlying idea is well studied: long prompts increase memory, latency, and cost, while prompt/context compression attempts to remove redundancy without removing the information the model needs. Relevant work includes:
- Selective Context, which reports lower memory and inference time by pruning redundant context.
- LLMLingua, a coarse-to-fine prompt compression approach.
- LLMLingua-2, which frames prompt compression as faithful token classification.
- Prompt Compression for Large Language Models: A Survey, a broader map of hard and soft prompt compression methods.
- Lost in the Middle, a reminder that longer context is not automatically better-used context.
Read the technical note: docs/technology.md.
- Python 3.10+
- A running Headroom proxy writing
~/.headroom/logs/proxy.log - A terminal that supports ANSI escape codes
No Python packages are required.
Run checks:
python3 -m py_compile bin/headroom-meter
bin/headroom-meter --once --color never --asciiRun the local installer:
./install.sh- compact mode for narrow terminals
- optional exportable session summary
- better synthetic fixture tests
- terminal recording for the README
If this makes Headroom feel easier to understand, star the repo so other Codex and Headroom users can find it.
MIT