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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
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.pngnew file mode 100644index 000000000..92a7ee4deBinary files /dev/null and b/docs/assets/pr-screenshots/pr-1369-co2-card.png differdiff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.htmlindex 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.pyindex 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_namelogger = 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_ENVDEFAULT_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.pynew file mode 100644index 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 co2diff --git a/tests/test_dashboard_co2_playwright.py b/tests/test_dashboard_co2_playwright.pynew file mode 100644index 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()