Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(dashboard): add CO₂ Saved card to dashboard and /stats API (#1369)

Peter Lodri2bc941946715
diff --git a/docs/assets/pr-screenshots/pr-1369-co2-card.png b/docs/assets/pr-screenshots/pr-1369-co2-card.png
new file mode 100644
index 000000000..92a7ee4de
Binary files /dev/null and b/docs/assets/pr-screenshots/pr-1369-co2-card.png differ
diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.html
index 62eff345e..bfe533ccd 100644
--- a/headroom/dashboard/templates/dashboard.html
+++ b/headroom/dashboard/templates/dashboard.html
@@ -798,7 +798,7 @@
</div>
<div class="p-4">
- <div class="grid grid-cols-1 md:grid-cols-4 gap-3 mb-5">
+ <div class="grid grid-cols-1 md:grid-cols-5 gap-3 mb-5">
<div class="rounded-lg border border-border bg-card-alt p-3">
<div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Before</div>
<div class="text-2xl font-light tabular-nums" x-text="formatNumber(stats.agent_usage?.totals?.before_tokens || 0)"></div>
@@ -815,6 +815,13 @@
<div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Savings</div>
<div class="text-2xl font-light tabular-nums text-emerald-400" x-text="(stats.agent_usage?.totals?.savings_percent || 0).toFixed(1) + '%'"></div>
</div>
+ <div class="rounded-lg border border-border bg-card-alt p-3"
+ :title="stats.co2?.methodology || 'EcoLogits energy model x IEA 2023 carbon intensity'">
+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">CO2 Saved</div>
+ <div class="text-2xl font-light tabular-nums text-green-400"
+ x-text="formatCO2(stats.co2?.co2_saved_mg || 0)"></div>
+ <div class="text-xs text-gray-600 mt-0.5">EcoLogits est.</div>
+ </div>
</div>
<template x-if="agentRows.length > 0">
@@ -2324,6 +2331,14 @@
return n.toString();
},
+ formatCO2(mg) {
+ if (mg <= 0) return '0 mg';
+ if (mg >= 1000000) return (mg / 1000000).toFixed(2) + ' kg';
+ if (mg >= 1000) return (mg / 1000).toFixed(2) + ' g';
+ if (mg >= 1) return mg.toFixed(1) + ' mg';
+ return mg.toFixed(3) + ' mg';
+ },
+
formatCurrency(n) {
if (n < 0) return '-' + this.formatCurrency(-n);
if (n >= 1000) return (n / 1000).toFixed(1) + 'k';
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index 9dd767f99..101474ab0 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -32,6 +32,38 @@ sanitize_project_name = project_name_policy.sanitize_project_name
logger = logging.getLogger(__name__)
+_CO2_MODEL_WH_PER_TOKEN: dict[str, float] = {
+ "claude-opus": 0.0005,
+ "claude-sonnet": 0.0003,
+ "claude-haiku": 0.00008,
+ "gpt-4": 0.0004,
+ "gpt-4o": 0.0003,
+ "gpt-4o-mini": 0.00008,
+ "o1": 0.0006,
+ "o3": 0.0006,
+ "gemini-1.5-pro": 0.0003,
+ "gemini-1.5-flash": 0.00008,
+}
+_CO2_DEFAULT_WH_PER_TOKEN = 0.0002
+_CO2_CARBON_INTENSITY_KG_PER_KWH = 0.4
+
+
+def estimate_co2_saved_mg(tokens_saved: int, model: str = "") -> float:
+ """Estimate CO2 saved in milligrams from avoided input tokens."""
+ if tokens_saved <= 0:
+ return 0.0
+
+ model_lower = model.lower()
+ wh_per_token = _CO2_DEFAULT_WH_PER_TOKEN
+ for key, value in _CO2_MODEL_WH_PER_TOKEN.items():
+ if key in model_lower:
+ wh_per_token = value
+ break
+
+ grams_per_token = wh_per_token * _CO2_CARBON_INTENSITY_KG_PER_KWH
+ return float(tokens_saved) * grams_per_token * 1000
+
+
HEADROOM_SAVINGS_PATH_ENV_VAR = _paths.HEADROOM_SAVINGS_PATH_ENV
DEFAULT_SAVINGS_DIR = ".headroom"
DEFAULT_SAVINGS_FILE = "proxy_savings.json"
@@ -1551,9 +1583,11 @@ class SavingsTracker:
response["projects"] = self._projects_snapshot_locked()
return response
- def stats_preview(self, recent_points: int = 20) -> dict[str, Any]:
+ def stats_preview(self, recent_points: int = 20, model: str = "") -> dict[str, Any]:
"""Return a compact preview for `/stats`."""
snapshot = self.snapshot()
+ tokens_saved = _coerce_int(snapshot["lifetime"].get("tokens_saved"))
+ co2_mg = estimate_co2_saved_mg(tokens_saved, model=model)
return {
"schema_version": snapshot["schema_version"],
"storage_path": snapshot["storage_path"],
@@ -1566,6 +1600,13 @@ class SavingsTracker:
"projects": snapshot["projects"],
"projects_limit": DEFAULT_MAX_PROJECTS,
"by_model": snapshot["by_model"],
+ "co2": {
+ "tokens_saved": tokens_saved,
+ "co2_saved_mg": round(co2_mg, 3),
+ "co2_saved_g": round(co2_mg / 1000, 6),
+ "methodology": "EcoLogits v0.8 energy model x IEA 2023 global carbon intensity (0.4 kg CO2/kWh)",
+ "note": "Conservative estimate. Actual savings vary by provider data center region.",
+ },
}
def history_response(self, history_mode: str = "compact") -> dict[str, Any]:
diff --git a/tests/test_co2_estimation.py b/tests/test_co2_estimation.py
new file mode 100644
index 000000000..21a6e43d3
--- /dev/null
+++ b/tests/test_co2_estimation.py
@@ -0,0 +1,67 @@
+"""Tests for CO₂ saved estimation in savings_tracker.
+
+Validates estimate_co2_saved_mg() and its presence in stats_preview().
+"""
+
+from __future__ import annotations
+
+from headroom.proxy.savings_tracker import estimate_co2_saved_mg
+
+
+def test_zero_tokens_returns_zero() -> None:
+ assert estimate_co2_saved_mg(0) == 0.0
+ assert estimate_co2_saved_mg(-100) == 0.0
+
+
+def test_positive_tokens_returns_positive() -> None:
+ result = estimate_co2_saved_mg(1_000_000)
+ assert result > 0
+
+
+def test_claude_sonnet_uses_correct_factor() -> None:
+ # claude-sonnet: 0.0003 Wh/token × 0.4 kg/kWh × 1000 mg/g = 0.12 mg/token
+ result = estimate_co2_saved_mg(1000, model="claude-sonnet-4-5")
+ assert abs(result - 120.0) < 1.0 # 0.12 mg × 1000 = 120 mg
+
+
+def test_unknown_model_uses_default_factor() -> None:
+ # default: 0.0002 Wh/token × 0.4 = 0.08 mg/token
+ result = estimate_co2_saved_mg(1000, model="unknown-model-xyz")
+ assert abs(result - 80.0) < 1.0
+
+
+def test_claude_haiku_lower_than_sonnet() -> None:
+ haiku = estimate_co2_saved_mg(1000, model="claude-haiku")
+ sonnet = estimate_co2_saved_mg(1000, model="claude-sonnet")
+ assert haiku < sonnet
+
+
+def test_large_savings_in_grams() -> None:
+ # 1M tokens at claude-sonnet = 120,000 mg = 120 g
+ mg = estimate_co2_saved_mg(1_000_000, model="claude-sonnet")
+ g = mg / 1000
+ assert abs(g - 120.0) < 1.0
+
+
+def test_stats_preview_includes_co2() -> None:
+ """stats_preview() must include a co2 block with co2_saved_mg."""
+ import pathlib
+ import tempfile
+
+ from headroom.proxy.savings_tracker import SavingsTracker
+
+ with tempfile.TemporaryDirectory() as tmp:
+ tracker = SavingsTracker(path=str(pathlib.Path(tmp) / "savings.json"))
+ tracker.record_compression_savings(
+ model="claude-sonnet-4-5",
+ tokens_saved=10_000,
+ )
+ preview = tracker.stats_preview(model="claude-sonnet-4-5")
+
+ assert "co2" in preview
+ co2 = preview["co2"]
+ assert "co2_saved_mg" in co2
+ assert co2["co2_saved_mg"] > 0
+ assert "co2_saved_g" in co2
+ assert co2["co2_saved_g"] == round(co2["co2_saved_mg"] / 1000, 6)
+ assert "methodology" in co2
diff --git a/tests/test_dashboard_co2_playwright.py b/tests/test_dashboard_co2_playwright.py
new file mode 100644
index 000000000..8e8a4a40f
--- /dev/null
+++ b/tests/test_dashboard_co2_playwright.py
@@ -0,0 +1,34 @@
+"""Playwright coverage for the dashboard CO2 savings card."""
+
+from __future__ import annotations
+
+import copy
+
+import pytest
+
+from tests.test_dashboard_cache_lifetime_playwright import _open_dashboard
+from tests.test_dashboard_cache_ttl_playwright import _sample_stats
+
+playwright = pytest.importorskip("playwright.sync_api")
+expect = playwright.expect
+sync_playwright = playwright.sync_playwright
+
+
+def test_co2_card_renders_estimated_savings() -> None:
+ stats = copy.deepcopy(_sample_stats())
+ stats["co2"] = {
+ "co2_saved_mg": 120_000,
+ "co2_saved_g": 120,
+ "methodology": "EcoLogits energy model x IEA 2023 global carbon intensity",
+ }
+
+ with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page(viewport={"width": 1440, "height": 1000})
+ _open_dashboard(page, stats)
+
+ expect(page.get_by_text("CO2 Saved", exact=True)).to_be_visible()
+ expect(page.get_by_text("120.00 g", exact=True)).to_be_visible()
+ expect(page.get_by_text("EcoLogits est.", exact=True)).to_be_visible()
+
+ browser.close()