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
Add wrap commands for Codex/Cursor/Aider with rtk instructions, fix savings metrics
chopratejase2aac4863a4f
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 744d3ac10..f42b9d9ad 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -2,6 +2,9 @@Usage:headroom wrap claude # Start proxy + rtk + claude+ headroom wrap codex # Start proxy + OpenAI Codex CLI+ headroom wrap aider # Start proxy + aider+ headroom wrap cursor # Start proxy + print Cursor config instructionsheadroom wrap claude --no-rtk # Without rtk hooksheadroom wrap claude --port 9999 # Custom proxy portheadroom wrap claude -- --model opus # Pass args to claude@@ -112,6 +115,184 @@ def _setup_rtk(verbose: bool = False) -> Path | None:return rtk_path+# rtk instructions for tools without hook support (Codex, Cursor, Aider).+# These get injected into AGENTS.md / .cursorrules so the LLM voluntarily+# uses rtk-prefixed commands. Kept concise to minimize instruction overhead.+RTK_INSTRUCTIONS_BLOCK = """\+<!-- headroom:rtk-instructions -->+# RTK (Rust Token Killer) - Token-Optimized Commands++When running shell commands, **always prefix with `rtk`**. This reduces context+usage by 60-90% with zero behavior change. If rtk has no filter for a command,+it passes through unchanged — so it is always safe to use.++## Key Commands+```bash+# Git (59-80% savings)+rtk git status rtk git diff rtk git log++# Files & Search (60-75% savings)+rtk ls <path> rtk read <file> rtk grep <pattern>+rtk find <pattern> rtk diff <file>++# Test (90-99% savings) — shows failures only+rtk pytest tests/ rtk cargo test rtk test <cmd>++# Build & Lint (80-90% savings) — shows errors only+rtk tsc rtk lint rtk cargo build+rtk prettier --check rtk mypy rtk ruff check++# Analysis (70-90% savings)+rtk err <cmd> rtk log <file> rtk json <file>+rtk summary <cmd> rtk deps rtk env++# GitHub (26-87% savings)+rtk gh pr view <n> rtk gh run list rtk gh issue list++# Infrastructure (85% savings)+rtk docker ps rtk kubectl get rtk docker logs <c>++# Package managers (70-90% savings)+rtk pip list rtk pnpm install rtk npm run <script>+```++## Rules+- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`+- For debugging, use raw command without rtk prefix+- `rtk proxy <cmd>` runs command without filtering but tracks usage+<!-- /headroom:rtk-instructions -->+"""++# Marker used to detect if instructions are already injected+_RTK_MARKER = "<!-- headroom:rtk-instructions -->"+++def _ensure_rtk_binary(verbose: bool = False) -> Path | None:+ """Ensure rtk binary is installed (download if needed). No hook registration."""+ from headroom.rtk import get_rtk_path+ from headroom.rtk.installer import ensure_rtk++ rtk_path = get_rtk_path()++ if rtk_path:+ if verbose:+ click.echo(f" rtk found at {rtk_path}")+ return rtk_path++ click.echo(" Downloading rtk (Rust Token Killer)...")+ rtk_path = ensure_rtk()+ if rtk_path:+ click.echo(f" rtk installed at {rtk_path}")+ return rtk_path++ click.echo(" rtk download failed — continuing without it")+ return None+++def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:+ """Inject rtk instructions into a file (AGENTS.md, .cursorrules, etc.).++ Idempotent — skips if marker already present. Appends to existing content.+ Returns True if instructions were written.+ """+ if file_path.exists():+ existing = file_path.read_text()+ if _RTK_MARKER in existing:+ if verbose:+ click.echo(f" rtk instructions already in {file_path.name}")+ return True+ # Append to existing file+ with open(file_path, "a") as f:+ f.write("\n\n" + RTK_INSTRUCTIONS_BLOCK)+ else:+ file_path.parent.mkdir(parents=True, exist_ok=True)+ file_path.write_text(RTK_INSTRUCTIONS_BLOCK)++ click.echo(f" rtk instructions injected into {file_path}")+ return True+++def _ensure_proxy(port: int, no_proxy: bool) -> subprocess.Popen | None:+ """Start or verify proxy. Returns process handle if we started it."""+ if not no_proxy:+ if _check_proxy(port):+ click.echo(f" Proxy already running on port {port}")+ return None+ else:+ click.echo(f" Starting Headroom proxy on port {port}...")+ try:+ proc = _start_proxy(port)+ click.echo(f" Proxy ready on http://127.0.0.1:{port}")+ return proc+ except RuntimeError as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ else:+ if not _check_proxy(port):+ click.echo(f" Warning: No proxy detected on port {port}")+ return None+++def _make_cleanup(proxy_proc_holder: list) -> Any:+ """Create a cleanup function that terminates the proxy on exit."""++ def cleanup(signum: int | None = None, frame: Any = None) -> None:+ proc = proxy_proc_holder[0] if proxy_proc_holder else None+ if proc and proc.poll() is None:+ proc.terminate()+ try:+ proc.wait(timeout=5)+ except subprocess.TimeoutExpired:+ proc.kill()++ return cleanup+++def _launch_tool(+ binary: str,+ args: tuple,+ env: dict[str, str],+ port: int,+ no_proxy: bool,+ tool_label: str,+ env_vars_display: list[str],+) -> None:+ """Common logic: start proxy, launch tool, clean up."""+ proxy_holder: list[subprocess.Popen | None] = [None]+ cleanup = _make_cleanup(proxy_holder)+ signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGTERM, cleanup)++ try:+ click.echo()+ padded = f"HEADROOM WRAP: {tool_label}".center(47)+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(f" ║{padded}║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ proxy_holder[0] = _ensure_proxy(port, no_proxy)++ click.echo()+ click.echo(f" Launching {tool_label} (API routed through Headroom)...")+ for var in env_vars_display:+ click.echo(f" {var}")+ if args:+ click.echo(f" Extra args: {' '.join(args)}")+ click.echo()++ result = subprocess.run([binary, *args], env=env)+ raise SystemExit(result.returncode)++ except SystemExit:+ raise+ except Exception as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ finally:+ cleanup()++@main.group()def wrap() -> None:"""Wrap CLI tools to run through Headroom.@@ -121,13 +302,19 @@ def wrap() -> None:the target tool so all API calls route through Headroom automatically.\b- Example:- headroom wrap claude # Proxy + rtk + Claude Code- headroom wrap claude --no-rtk # Proxy only, no rtk hooks- headroom wrap claude -- -p # Pass --print flag to claude+ Supported tools:+ headroom wrap claude # Claude Code (Anthropic)+ headroom wrap codex # OpenAI Codex CLI+ headroom wrap aider # Aider+ headroom wrap cursor # Cursor (prints config instructions)"""+# =============================================================================+# Claude Code+# =============================================================================++@wrap.command()@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and hook registration")@@ -138,17 +325,7 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:"""Launch Claude Code through Headroom proxy.\b- This command:- 1. Starts a Headroom optimization proxy on localhost- 2. Installs rtk and registers Claude Code hooks (compresses CLI output)- 3. Sets ANTHROPIC_API_URL to route through the proxy- 4. Launches 'claude' with your arguments-- \b- All API calls from Claude Code flow through Headroom, which:- - Compresses tool outputs (SmartCrusher, Kompress, CodeCompressor)- - Preserves prefix cache (frozen message optimization)- - Tracks token savings and cache hit rates+ Sets ANTHROPIC_BASE_URL to route all Anthropic API calls through Headroom.\bExamples:@@ -157,24 +334,15 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:headroom wrap claude --port 9999 # Custom proxy portheadroom wrap claude --no-rtk # Skip rtk (proxy only)"""- # Check that claude CLI is availableclaude_bin = shutil.which("claude")if not claude_bin:click.echo("Error: 'claude' not found in PATH.")click.echo("Install Claude Code: https://docs.anthropic.com/en/docs/claude-code")raise SystemExit(1)- proxy_proc: subprocess.Popen | None = None-- def cleanup(signum: int | None = None, frame: Any = None) -> None:- """Clean up proxy on exit."""- if proxy_proc and proxy_proc.poll() is None:- proxy_proc.terminate()- try:- proxy_proc.wait(timeout=5)- except subprocess.TimeoutExpired:- proxy_proc.kill()-+ # Setup rtk before launching (Claude-specific)+ proxy_holder: list[subprocess.Popen | None] = [None]+ cleanup = _make_cleanup(proxy_holder)signal.signal(signal.SIGINT, cleanup)signal.signal(signal.SIGTERM, cleanup)@@ -185,31 +353,14 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:click.echo(" ╚═══════════════════════════════════════════════╝")click.echo()- # Step 1: Start proxy- if not no_proxy:- if _check_proxy(port):- click.echo(f" Proxy already running on port {port}")- else:- click.echo(f" Starting Headroom proxy on port {port}...")- try:- proxy_proc = _start_proxy(port)- click.echo(f" Proxy ready on http://127.0.0.1:{port}")- except RuntimeError as e:- click.echo(f" Error: {e}")- raise SystemExit(1) from e- else:- if not _check_proxy(port):- click.echo(f" Warning: No proxy detected on port {port}")+ proxy_holder[0] = _ensure_proxy(port, no_proxy)- # Step 2: Setup rtkif not no_rtk:click.echo(" Setting up rtk...")_setup_rtk(verbose=verbose)- else:- if verbose:- click.echo(" Skipping rtk (--no-rtk)")+ elif verbose:+ click.echo(" Skipping rtk (--no-rtk)")- # Step 3: Launch claudeclick.echo()click.echo(" Launching Claude Code (API routed through Headroom)...")click.echo(f" ANTHROPIC_BASE_URL=http://127.0.0.1:{port}")@@ -220,12 +371,7 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:env = os.environ.copy()env["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"- # Run claude — this blocks until claude exits- result = subprocess.run(- [claude_bin, *claude_args],- env=env,- )-+ result = subprocess.run([claude_bin, *claude_args], env=env)raise SystemExit(result.returncode)except SystemExit:@@ -235,3 +381,213 @@ def claude(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, claude_args:raise SystemExit(1) from efinally:cleanup()+++# =============================================================================+# OpenAI Codex CLI+# =============================================================================++[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and AGENTS.md injection")[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("codex_args", nargs=-1, type=click.UNPROCESSED)+def codex(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, codex_args: tuple) -> None:+ """Launch OpenAI Codex CLI through Headroom proxy.++ \b+ Sets OPENAI_BASE_URL to route all OpenAI API calls through Headroom.+ Installs rtk and injects instructions into AGENTS.md so Codex uses+ token-optimized commands (60-90% savings on shell output).++ \b+ Examples:+ headroom wrap codex # Start proxy + rtk + codex+ headroom wrap codex -- "fix the bug" # Pass prompt to codex+ headroom wrap codex --no-rtk # Skip rtk setup+ headroom wrap codex --port 9999 # Custom proxy port+ """+ codex_bin = shutil.which("codex")+ if not codex_bin:+ click.echo("Error: 'codex' not found in PATH.")+ click.echo("Install Codex CLI: npm install -g @openai/codex")+ raise SystemExit(1)++ # Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)+ if not no_rtk:+ click.echo(" Setting up rtk for Codex...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ # Inject into project AGENTS.md (Codex reads this automatically)+ agents_md = Path.cwd() / "AGENTS.md"+ _inject_rtk_instructions(agents_md, verbose=verbose)++ # Also inject into global ~/.codex/AGENTS.md+ global_agents = Path.home() / ".codex" / "AGENTS.md"+ _inject_rtk_instructions(global_agents, verbose=verbose)++ env = os.environ.copy()+ env["OPENAI_BASE_URL"] = f"http://127.0.0.1:{port}/v1"++ _launch_tool(+ binary=codex_bin,+ args=codex_args,+ env=env,+ port=port,+ no_proxy=no_proxy,+ tool_label="CODEX",+ env_vars_display=[f"OPENAI_BASE_URL=http://127.0.0.1:{port}/v1"],+ )+++# =============================================================================+# Aider+# =============================================================================++[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and conventions injection")[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")[email protected]("aider_args", nargs=-1, type=click.UNPROCESSED)+def aider(port: int, no_rtk: bool, no_proxy: bool, verbose: bool, aider_args: tuple) -> None:+ """Launch aider through Headroom proxy.++ \b+ Sets OPENAI_API_BASE to route all API calls through Headroom.+ Installs rtk and injects instructions into .aider.conf.yml conventions+ so aider uses token-optimized commands.++ \b+ Examples:+ headroom wrap aider # Start proxy + rtk + aider+ headroom wrap aider -- --model gpt-4o # Use GPT-4o+ headroom wrap aider -- --model claude-sonnet-4 # Use Claude+ headroom wrap aider --no-rtk # Skip rtk setup+ """+ aider_bin = shutil.which("aider")+ if not aider_bin:+ click.echo("Error: 'aider' not found in PATH.")+ click.echo("Install aider: pip install aider-chat")+ raise SystemExit(1)++ # Setup rtk for aider (binary + CONVENTIONS.md instructions)+ if not no_rtk:+ click.echo(" Setting up rtk for aider...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ # aider reads CONVENTIONS.md from project root+ conventions = Path.cwd() / "CONVENTIONS.md"+ _inject_rtk_instructions(conventions, verbose=verbose)++ env = os.environ.copy()+ env["OPENAI_API_BASE"] = f"http://127.0.0.1:{port}/v1"+ env["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"++ _launch_tool(+ binary=aider_bin,+ args=aider_args,+ env=env,+ port=port,+ no_proxy=no_proxy,+ tool_label="AIDER",+ env_vars_display=[+ f"OPENAI_API_BASE=http://127.0.0.1:{port}/v1",+ f"ANTHROPIC_BASE_URL=http://127.0.0.1:{port}",+ ],+ )+++# =============================================================================+# Cursor+# =============================================================================++[email protected]("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")[email protected]("--no-rtk", is_flag=True, help="Skip rtk installation and .cursorrules injection")[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")+def cursor(port: int, no_rtk: bool, no_proxy: bool, verbose: bool) -> None:+ """Start Headroom proxy for use with Cursor.++ \b+ Cursor reads its API configuration from its settings UI, not from+ environment variables. This command starts the proxy, installs rtk+ with .cursorrules instructions, and prints the Cursor settings.++ \b+ After running this command, open Cursor and configure:+ Settings > Models > OpenAI API Key > Advanced > Override Base URL++ \b+ Example:+ headroom wrap cursor # Start proxy + rtk + instructions+ headroom wrap cursor --no-rtk # Proxy only, no rtk+ headroom wrap cursor --port 9999 # Custom proxy port+ """+ proxy_holder: list[subprocess.Popen | None] = [None]+ cleanup = _make_cleanup(proxy_holder)+ signal.signal(signal.SIGINT, cleanup)+ signal.signal(signal.SIGTERM, cleanup)++ try:+ click.echo()+ click.echo(" ╔═══════════════════════════════════════════════╗")+ click.echo(" ║ HEADROOM WRAP: CURSOR ║")+ click.echo(" ╚═══════════════════════════════════════════════╝")+ click.echo()++ proxy_holder[0] = _ensure_proxy(port, no_proxy)++ # Setup rtk for Cursor (binary + .cursorrules instructions)+ if not no_rtk:+ click.echo(" Setting up rtk for Cursor...")+ rtk_path = _ensure_rtk_binary(verbose=verbose)+ if rtk_path:+ cursorrules = Path.cwd() / ".cursorrules"+ _inject_rtk_instructions(cursorrules, verbose=verbose)++ click.echo()+ click.echo(" Headroom proxy is running. Configure Cursor:")+ click.echo()+ click.echo(" For OpenAI models:")+ click.echo(f" Base URL: http://127.0.0.1:{port}/v1")+ click.echo(" API Key: your-openai-api-key")+ click.echo()+ click.echo(" For Anthropic models:")+ click.echo(f" Base URL: http://127.0.0.1:{port}")+ click.echo(" API Key: your-anthropic-api-key")+ click.echo()+ click.echo(" In Cursor:")+ click.echo(" Settings > Models > OpenAI API Key > Override OpenAI Base URL")+ click.echo(f" Set to: http://127.0.0.1:{port}/v1")+ if not no_rtk:+ click.echo()+ click.echo(" rtk instructions injected into .cursorrules")+ click.echo(" Cursor will use token-optimized commands automatically.")+ click.echo()+ click.echo(" Press Ctrl+C to stop the proxy.")+ click.echo()++ # Block until Ctrl+C+ try:+ while True:+ time.sleep(1)+ proc = proxy_holder[0]+ if proc and proc.poll() is not None:+ click.echo(" Proxy process exited unexpectedly.")+ raise SystemExit(1)+ except KeyboardInterrupt:+ click.echo("\n Shutting down...")++ except SystemExit:+ raise+ except Exception as e:+ click.echo(f" Error: {e}")+ raise SystemExit(1) from e+ finally:+ cleanup()diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex f7364e25c..a4ff5727e 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -217,6 +217,46 @@ _CACHE_ECONOMICS = {}+def _get_rtk_stats() -> dict[str, Any] | None:+ """Get rtk (Rust Token Killer) savings stats if rtk is installed.++ Reads from rtk's tracking database via `rtk gain --format json`.+ Returns None if rtk is not installed.+ """+ import shutil+ import subprocess as _sp++ rtk_bin = shutil.which("rtk")+ if not rtk_bin:+ # Check headroom-managed install+ rtk_managed = Path.home() / ".headroom" / "bin" / "rtk"+ if rtk_managed.exists():+ rtk_bin = str(rtk_managed)+ else:+ return None++ try:+ result = _sp.run(+ [rtk_bin, "gain", "--format", "json"],+ capture_output=True,+ text=True,+ timeout=5,+ )+ if result.returncode == 0 and result.stdout.strip():+ data = json.loads(result.stdout)+ summary = data.get("summary", {})+ return {+ "installed": True,+ "total_commands": summary.get("total_commands", 0),+ "tokens_saved": summary.get("total_saved", 0),+ "avg_savings_pct": summary.get("avg_savings_pct", 0.0),+ }+ except Exception:+ pass++ return {"installed": True, "total_commands": 0, "tokens_saved": 0, "avg_savings_pct": 0.0}++def _build_prefix_cache_stats(metrics: PrometheusMetrics,cost_tracker: CostTracker | None,@@ -322,24 +362,27 @@ def _build_prefix_cache_stats(metrics.prefix_freeze_tokens_preserved - metrics.prefix_freeze_compression_foregone),},+ "attribution": (+ "Prefix caching is performed by the LLM provider (Anthropic, OpenAI). "+ "Headroom reports cache stats as observed from API responses. "+ "CacheAligner and prefix freeze improve cache hit rates by stabilizing "+ "the message prefix, but baseline caching happens without Headroom."+ ),}def _merge_cost_stats(cost_stats: dict | None,cache_stats: dict,+ cli_tokens_avoided: int = 0,) -> dict | None:- """Add prefix cache savings to overall cost stats.-- Compression savings and cache savings are computed on different token- scopes (Headroom tracks user-message tokens; Anthropic's cache metrics- cover the entire prompt including system/tools). We keep both as- additive line items without cross-contaminating the counterfactual.+ """Add prefix cache and CLI filtering savings to overall cost stats.- - compression_savings_usd: from removing tokens (CostTracker scope)- - cache_savings_usd: from prefix cache discounts (full-prompt scope)- - savings_usd: sum of both (hero metric)- - cost_with/without_headroom_usd: unchanged (compression scope only)+ Three savings layers, each on a different scope:+ - compression_savings_usd: tokens removed by proxy (SmartCrusher, etc.)+ - cache_savings_usd: prefix cache discount from provider+ - cli_filtering_savings_usd: tokens avoided by rtk before reaching context+ - savings_usd: sum of all (hero metric)"""if cost_stats is None:return None@@ -347,11 +390,24 @@ def _merge_cost_stats(cache_net = cache_stats.get("totals", {}).get("net_savings_usd", 0.0)compression_savings = cost_stats.get("savings_usd", 0.0)+ # Estimate CLI filtering savings: tokens_avoided * avg input price+ # Use the average input price from the cost tracker if available+ cli_savings_usd = 0.0+ if cli_tokens_avoided > 0 and LITELLM_AVAILABLE:+ # Use a conservative estimate: average across models seen+ total_input_cost = cost_stats.get("total_input_cost_usd", 0.0)+ total_input_tokens = cost_stats.get("total_input_tokens", 0)+ if total_input_tokens > 0:+ avg_price_per_token = total_input_cost / total_input_tokens+ cli_savings_usd = cli_tokens_avoided * avg_price_per_token+return {**cost_stats,- "savings_usd": round(compression_savings + cache_net, 4),+ "savings_usd": round(compression_savings + cache_net + cli_savings_usd, 4),"compression_savings_usd": round(compression_savings, 4),"cache_savings_usd": round(cache_net, 4),+ "cli_filtering_savings_usd": round(cli_savings_usd, 4),+ "cli_tokens_avoided": cli_tokens_avoided,}@@ -6240,10 +6296,42 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# Build prefix cache stats once (used in both prefix_cache and cost)prefix_cache_stats = _build_prefix_cache_stats(m, proxy.cost_tracker)+ # Fetch CLI filtering savings (rtk — tokens avoided before reaching context)+ cli_filtering_stats = _get_rtk_stats()+ cli_tokens_avoided = (+ cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0+ )+# Calculate total tokens before compressiontotal_tokens_before = m.tokens_input_total + m.tokens_saved_total+ # Build unified savings summary (all layers)+ compression_tokens = m.tokens_saved_total+ cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)+ total_tokens_all_layers = compression_tokens + cli_tokens_avoided+return {+ "savings": {+ "total_tokens": total_tokens_all_layers,+ "by_layer": {+ "cli_filtering": {+ "tokens": cli_tokens_avoided,+ "description": "Tokens avoided by CLI output filtering (rtk) before reaching context",+ },+ "compression": {+ "tokens": compression_tokens,+ "description": "Tokens removed by proxy compression (SmartCrusher, ContentRouter, etc.)",+ },+ "prefix_cache": {+ "discount_usd": round(cache_net_usd, 4),+ "description": (+ "Cost discount from provider prefix caching. "+ "Headroom's CacheAligner improves hit rates; "+ "baseline caching is provider-native."+ ),+ },+ },+ },"requests": {"total": m.requests_total,"cached": m.requests_cached,@@ -6256,6 +6344,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"input": m.tokens_input_total,"output": m.tokens_output_total,"saved": m.tokens_saved_total,+ "cli_tokens_avoided": cli_tokens_avoided,"total_before_compression": total_tokens_before,"savings_percent": round((m.tokens_saved_total / total_tokens_before * 100)@@ -6298,6 +6387,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"cost": _merge_cost_stats(proxy.cost_tracker.stats() if proxy.cost_tracker else None,prefix_cache_stats,+ cli_tokens_avoided=cli_tokens_avoided,),"compression": {"ccr_entries": compression_stats.get("entry_count", 0),@@ -6327,6 +6417,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:),},"toin": get_toin().get_stats(),+ "cli_filtering": cli_filtering_stats,"cache": await proxy.cache.stats() if proxy.cache else None,"rate_limiter": await proxy.rate_limiter.stats() if proxy.rate_limiter else None,"recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],diff --git a/tests/test_memory_tracker_integration.py b/tests/test_memory_tracker_integration.pyindex 6be8ef62c..831dcdd7d 100644--- a/tests/test_memory_tracker_integration.py+++ b/tests/test_memory_tracker_integration.py@@ -445,9 +445,14 @@ class TestProcessStatsCollection:stats = tracker.get_process_stats()- # Should have real values from the current process- assert stats.rss_bytes > 0 # Process must use some memory- assert stats.vms_bytes > 0+ # psutil is optional — without it, stats are all zeros (graceful degradation)+ try:+ import psutil # noqa: F401++ assert stats.rss_bytes > 0 # Process must use some memory+ assert stats.vms_bytes > 0+ except ImportError:+ assert stats.rss_bytes == 0 # No psutil → zeros expectedassert stats.percent >= 0 # Could be 0 on some systemsdef test_process_stats_in_report(self):@@ -456,5 +461,11 @@ class TestProcessStatsCollection:report = tracker.get_report()- assert report.process.rss_bytes > 0- assert report.process.rss_mb > 0+ try:+ import psutil # noqa: F401++ assert report.process.rss_bytes > 0+ assert report.process.rss_mb > 0+ except ImportError:+ # Without psutil, process stats are zeros — that's expected+ assert report.process.rss_bytes == 0