Idea: headroom-stats — A Built-in Terminal Dashboard for Savings Analytics

[fxerkan]

Summary

I built a terminal-based savings dashboard for Headroom called headroom-stats and would love to see something like this included natively in the project. It gives users a real-time, at-a-glance view of exactly how much Headroom is saving them — which I think is a compelling way to demonstrate value and keep users engaged.

What it shows

• Overview panel: Lifetime tokens saved, cost saved, total requests, proxy status & PID
• • This Session: Requests, tokens saved, cost saved, savings %, input tokens, compression rate, best/avg savings
• • Savings Over Time: Bar chart of token & cost savings per time interval
• • Per-Project Breakdown: Tokens saved, cost saved, savings %, and request share per project
• • Daily Breakdown: Token and cost savings per day with visual bars
• • Agent Usage: Per-model breakdown (e.g. claude-sonnet-4-6) with before/after token counts

Screenshot

Real output from my machine (840 requests, 20M tokens saved, $59.91 saved lifetime)

Example Implementation

Here is a simplified version of the core rendering logic (Python + Rich):

#!/usr/bin/env python3
# headroom-stats: Terminal dashboard for Headroom savings analytics
# Requirements: pip install rich

import json
from pathlib import Path
from rich.console import Console
from rich.table import Table
from rich.panel import Panel
from rich.live import Live
import time

HEADROOM_LOG = Path.home() / ".headroom" / "proxy_history.jsonl"

def format_tokens(n: int) -> str:
    if n >= 1_000_000:
        return f"{n / 1_000_000:.1f}M"
    if n >= 1_000:
        return f"{n / 1_000:.1f}K"
    return str(n)

def load_history():
    if not HEADROOM_LOG.exists():
        return []
    entries = []
    with open(HEADROOM_LOG) as f:
        for line in f:
            try:
                entries.append(json.loads(line.strip()))
            except json.JSONDecodeError:
                pass
    return entries

def render(console: Console):
    history = load_history()
    total_saved = sum(e.get("tokens_saved", 0) for e in history)
    total_cost = sum(e.get("cost_saved", 0.0) for e in history)
    total_reqs = len(history)

    # Overview
    overview = Table.grid(padding=(0, 2))
    overview.add_column(justify="center")
    overview.add_column(justify="center")
    overview.add_column(justify="center")
    overview.add_row(
        Panel(f"[bold green]{format_tokens(total_saved)}[/]\n[dim]lifetime[/]", title="Tokens Saved"),
        Panel(f"[bold green]${total_cost:.2f}[/]\n[dim]lifetime[/]", title="Cost Saved"),
        Panel(f"[bold cyan]{total_reqs}[/]\n[dim]lifetime[/]", title="Requests"),
    )
    console.print(Panel(overview, title="[bold]HEADROOM · SAVINGS DASHBOARD[/]"))

    # Per-project breakdown
    projects: dict[str, dict] = {}
    for e in history:
        proj = e.get("project", "unknown")
        p = projects.setdefault(proj, {"reqs": 0, "tokens": 0, "cost": 0.0, "input": 0})
        p["reqs"] += 1
        p["tokens"] += e.get("tokens_saved", 0)
        p["cost"] += e.get("cost_saved", 0.0)
        p["input"] += e.get("input_tokens", 0)

    tbl = Table(title="Per-Project Breakdown", show_lines=True)
    tbl.add_column("Project")
    tbl.add_column("Requests", justify="right")
    tbl.add_column("Tokens Saved", justify="right")
    tbl.add_column("Cost Saved", justify="right")
    tbl.add_column("Savings %", justify="right")

    for proj, data in sorted(projects.items(), key=lambda x: -x[1]["tokens"]):
        savings_pct = (data["tokens"] / data["input"] * 100) if data["input"] else 0
        tbl.add_row(
            proj,
            str(data["reqs"]),
            format_tokens(data["tokens"]),
            f"${data['cost']:.2f}",
            f"{savings_pct:.1f}%",
        )
    console.print(tbl)

if __name__ == "__main__":
    console = Console()
    with Live(console=console, refresh_per_second=1, screen=True) as live:
        while True:
            console.clear()
            render(console)
            time.sleep(2)

This can be invoked as:

headroom stats        # one-shot snapshot
headroom dashboard    # live auto-refreshing view

Why Built-in?

1. Validates value: Users instantly see ROI — I saved $59.91 lifetime and 20M tokens, which is a compelling number to surface.
2. 2. Retention: A live dashboard keeps users checking back and motivates them to route more traffic through Headroom.
3. 3. Debugging aid: Per-project and per-model breakdowns help users understand which projects benefit most and why.
4. 4. Low friction: No extra install required if shipped with Headroom.
      I am happy to open a PR implementing this if the idea sounds good. The Rich library is a well-maintained dependency (or it could be done with pure terminal ANSI codes to avoid adding deps).

Let me know what you think!

[fxerkan]

you can find the script at https://github.com/fxerkan/headroom-stats