A real-time terminal dashboard for Headroom — the token-optimization proxy for Claude. See your token savings, cache performance, and compression stats live, without leaving the terminal.
- Headroom proxy running locally
curl -fsSL https://raw.githubusercontent.com/sbnet/headroom-stats/main/install.sh | bashThis downloads a pre-built binary for your platform (Linux x86/arm64, macOS Intel/Apple Silicon) to ~/.local/bin. Re-run to update.
Custom install dir:
INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/sbnet/headroom-stats/main/install.sh | bashBuild from source (requires Rust 1.75+):
cargo install --git https://github.com/sbnet/headroom-stats# Reads ANTHROPIC_BASE_URL automatically (set by headroom)
headroom-stats
# Explicit proxy URL
headroom-stats --url http://localhost:8787
# Custom refresh interval (default: 5s)
headroom-stats --interval 10| Key | Action |
|---|---|
q / Esc |
Quit |
r |
Force immediate refresh |
headroom-stats polls the /stats HTTP endpoint exposed by the Headroom proxy and renders the response as a live TUI dashboard using ratatui. The dashboard refreshes automatically every N seconds (configurable) and also responds to force-refresh on demand.
The displayed metrics mirror what headroom perf reports from logs, but sourced from the live proxy instead:
| Section | Source |
|---|---|
| Request summary | requests.* + tokens.* |
| Per-model breakdown | cost.per_model.* |
| Prefix cache | prefix_cache.totals.* |
| Optimization overhead | overhead.* |
| Content router | router.route_counts |
| TOIN learning | toin.* |
- ratatui — terminal UI framework
- tokio — async runtime
- reqwest — HTTP client
- clap — CLI argument parsing
# 1. Bump the version in Cargo.toml
# 2. Commit + tag
git tag vX.Y.Z
git push origin vX.Y.Z
- Prefer small, focused pull requests.
- Keep changes pragmatic: small diffs, clear manual checks, explicit commit messages.
- Do not commit secrets or credentials in plain text.
- If you change deployment behavior, update this README.
If you identify a vulnerability or unsafe infra/deployment practice, open a private issue or contact the maintainer before public disclosure.
This project is licensed under MIT. See LICENSE.