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(cli): add `headroom inspect` to view original vs compressed content (#1595)
Manmit Singh942e916368fe
diff --git a/headroom/cli/__init__.py b/headroom/cli/__init__.pyindex 92b28b33a..529a20d65 100644--- a/headroom/cli/__init__.py+++ b/headroom/cli/__init__.py@@ -18,6 +18,7 @@ from . import ( # noqa: F401copilot_auth,evals,init,+ inspect,install,learn,mcp,diff --git a/headroom/cli/inspect.py b/headroom/cli/inspect.pynew file mode 100644index 000000000..5fe001221--- /dev/null+++ b/headroom/cli/inspect.py@@ -0,0 +1,183 @@+"""`headroom inspect` — view original vs compressed message content.++Headroom already exposes *quantitative* telemetry (token counts, ratios) but no+way to *see* what the compressor changed. This command reads the proxy's+loopback ``/transformations/feed`` endpoint — which carries the pre/post+message snapshots when the proxy runs with ``--log-messages`` — and renders, per+request, the original vs compressed content for each message with the changed+segments highlighted (stdlib unified diff, no new dependencies). See issue #1267.+"""++from __future__ import annotations++import difflib+import json+import os+from typing import Any++import click++from .main import main+++def _extract_text(content: Any) -> str:+ """Flatten a message's ``content`` (str or list of blocks) to plain text.++ Handles Anthropic/OpenAI text blocks, nested ``tool_result`` content, and+ falls back to a JSON dump for unrecognized block shapes so nothing is+ silently dropped from the diff.+ """+ if content is None:+ return ""+ if isinstance(content, str):+ return content+ if isinstance(content, list):+ parts: list[str] = []+ for block in content:+ if isinstance(block, str):+ parts.append(block)+ elif isinstance(block, dict):+ if isinstance(block.get("text"), str):+ parts.append(block["text"])+ elif isinstance(block.get("content"), (str, list)):+ parts.append(_extract_text(block.get("content")))+ else:+ parts.append(json.dumps(block, ensure_ascii=False, sort_keys=True))+ else:+ parts.append(str(block))+ return "\n".join(parts)+ return str(content)+++def _role(msg: Any) -> str:+ return str(msg.get("role", "?")) if isinstance(msg, dict) else "?"+++def _content_of(msg: Any) -> Any:+ return msg.get("content") if isinstance(msg, dict) else msg+++def _render_request(transformation: dict[str, Any], *, full: bool) -> None:+ rid = transformation.get("request_id") or "?"+ model = transformation.get("model") or "?"+ before = transformation.get("input_tokens_original")+ after = transformation.get("input_tokens_optimized")+ saved = transformation.get("tokens_saved")+ pct = transformation.get("savings_percent")+ transforms = ", ".join(transformation.get("transforms_applied") or []) or "none"++ click.echo(click.style(f"\n━━ {rid} {model}", bold=True))+ click.echo(f" tokens {before} → {after} (saved {saved}, {pct}%) transforms: {transforms}")++ originals = transformation.get("request_messages") or []+ compressed = transformation.get("compressed_messages") or []+ count = max(len(originals), len(compressed))+ any_change = False++ for i in range(count):+ original = originals[i] if i < len(originals) else {}+ comp = compressed[i] if i < len(compressed) else {}+ original_text = _extract_text(_content_of(original))+ comp_text = _extract_text(_content_of(comp))+ unchanged = original_text == comp_text+ if unchanged and not full:+ continue+ any_change = True+ role = _role(original) if original else _role(comp)+ click.echo(click.style(f"\n [{i}] {role}", fg="cyan"))+ if unchanged:+ click.echo(" (unchanged)")+ continue+ for line in difflib.unified_diff(+ original_text.splitlines(),+ comp_text.splitlines(),+ fromfile="original",+ tofile="compressed",+ lineterm="",+ ):+ color: str | None = None+ if line.startswith("+") and not line.startswith("+++"):+ color = "green"+ elif line.startswith("-") and not line.startswith("---"):+ color = "red"+ elif line.startswith("@@"):+ color = "yellow"+ click.echo(" " + (click.style(line, fg=color) if color else line))++ if not any_change:+ click.echo(+ " (no per-message content changes — savings came from "+ "structural / transform-level edits)"+ )++[email protected]("inspect")+ "--port",+ "-p",+ default=None,+ type=click.IntRange(1, 65535),+ envvar="HEADROOM_PORT",+ help="Proxy port to query (default: 8787, env: HEADROOM_PORT)",+)+ "--last",+ default=1,+ type=click.IntRange(min=1),+ help="Show the N most recent requests (default: 1)",+)+ "--format",+ "output_format",+ type=click.Choice(["text", "json"]),+ default="text",+ help="Output format (default: text). json emits the raw feed for offline diffing.",+)+ "--full",+ is_flag=True,+ help="Show unchanged messages too (default: only messages the compressor changed)",+)+def inspect_cmd(port: int | None, last: int, output_format: str, full: bool) -> None:+ """Show original vs compressed content for recent proxy requests.++ \b+ Requires a running proxy started with --log-messages (or --log-file), which+ captures the pre/post-compression message snapshots the diff reads.++ \b+ Examples:+ headroom inspect Inspect the most recent request+ headroom inspect --last 5 Inspect the 5 most recent requests+ headroom inspect --full Include unchanged messages+ headroom inspect --format json Raw feed for piping into another tool+ """+ from headroom.install.health import probe_json++ resolved_port = port if port is not None else int(os.environ.get("HEADROOM_PORT", "8787"))+ base_url = f"http://127.0.0.1:{resolved_port}"+ payload = probe_json(f"{base_url}/transformations/feed?limit={last}", timeout=5.0)++ if payload is None:+ raise click.ClickException(+ f"No reachable proxy on {base_url}. Start one with `headroom proxy` "+ "(or pass --port to point at a running instance)."+ )+ if not payload.get("log_full_messages"):+ raise click.ClickException(+ "The proxy isn't capturing message content, so there's nothing to diff. "+ "Restart it with `headroom proxy --log-messages`."+ )++ transformations = payload.get("transformations") or []+ if not transformations:+ click.echo("No requests recorded yet. Send traffic through the proxy and retry.")+ return++ if output_format == "json":+ click.echo(json.dumps(transformations, indent=2, ensure_ascii=False))+ return++ # The feed returns oldest→newest; show the most recent first.+ for transformation in reversed(transformations):+ _render_request(transformation, full=full)diff --git a/headroom/cli/main.py b/headroom/cli/main.pyindex 384d23fcb..b55c96e1e 100644--- a/headroom/cli/main.py+++ b/headroom/cli/main.py@@ -68,6 +68,7 @@ def _register_commands() -> None:doctor, # noqa: F401evals, # noqa: F401init, # noqa: F401+ inspect, # noqa: F401install, # noqa: F401learn, # noqa: F401mcp, # noqa: F401diff --git a/tests/test_cli_inspect.py b/tests/test_cli_inspect.pynew file mode 100644index 000000000..b6ab3a790--- /dev/null+++ b/tests/test_cli_inspect.py@@ -0,0 +1,105 @@+"""Tests for the `headroom inspect` command (issue #1267).++The command reads the proxy's loopback ``/transformations/feed`` endpoint and+renders original-vs-compressed content. Tests stub ``probe_json`` so no proxy+is required.++Tests invoke the real top-level CLI (``main``) so the shipped command path —+including subcommand registration — is exercised, not just the command object.+"""++from __future__ import annotations++import json+from unittest.mock import patch++from click.testing import CliRunner++from headroom.cli.inspect import _extract_text, _role+++def _run(args: list[str]):+ from headroom.cli.main import main++ return CliRunner().invoke(main, ["inspect", *args])+++def test_extract_text_handles_str_and_blocks() -> None:+ assert _extract_text("hello") == "hello"+ assert _extract_text([{"type": "text", "text": "a"}, {"type": "text", "text": "b"}]) == "a\nb"+ # Nested tool_result content.+ assert _extract_text([{"type": "tool_result", "content": [{"text": "x"}]}]) == "x"+ # Unknown block falls back to JSON, never silently dropped.+ assert "foo" in _extract_text([{"weird": "foo"}])+ assert _extract_text(None) == ""+++def test_role_extraction() -> None:+ assert _role({"role": "user"}) == "user"+ assert _role("not a dict") == "?"+++def test_no_proxy_errors_cleanly() -> None:+ with patch("headroom.install.health.probe_json", return_value=None):+ result = _run([])+ assert result.exit_code != 0+ assert "No reachable proxy" in result.output+++def test_log_messages_disabled_hint() -> None:+ payload = {"transformations": [], "log_full_messages": False}+ with patch("headroom.install.health.probe_json", return_value=payload):+ result = _run([])+ assert result.exit_code != 0+ assert "--log-messages" in result.output+++def test_empty_feed_message() -> None:+ payload = {"transformations": [], "log_full_messages": True}+ with patch("headroom.install.health.probe_json", return_value=payload):+ result = _run([])+ assert result.exit_code == 0+ assert "No requests recorded" in result.output+++def _feed_payload() -> dict:+ return {+ "log_full_messages": True,+ "transformations": [+ {+ "request_id": "req-1",+ "model": "gpt-4o",+ "input_tokens_original": 100,+ "input_tokens_optimized": 40,+ "tokens_saved": 60,+ "savings_percent": 60.0,+ "transforms_applied": ["SmartCrusher"],+ "request_messages": [+ {"role": "user", "content": "line one\nline two\nline three"},+ ],+ "compressed_messages": [+ {"role": "user", "content": "line one\nline three"},+ ],+ }+ ],+ }+++def test_text_render_shows_diff_and_header() -> None:+ with patch("headroom.install.health.probe_json", return_value=_feed_payload()):+ result = _run([])+ assert result.exit_code == 0+ out = result.output+ assert "req-1" in out+ assert "gpt-4o" in out+ assert "SmartCrusher" in out+ # The removed line shows up on the original side of the diff.+ assert "line two" in out+++def test_json_format_emits_raw_feed() -> None:+ with patch("headroom.install.health.probe_json", return_value=_feed_payload()):+ result = _run(["--format", "json"])+ assert result.exit_code == 0+ parsed = json.loads(result.output)+ assert parsed[0]["request_id"] == "req-1"diff --git a/wiki/cli.md b/wiki/cli.mdindex 8dad03ee5..7b7c8cbd1 100644--- a/wiki/cli.md+++ b/wiki/cli.md@@ -26,6 +26,7 @@ This page is the authoritative reference for the **Python Headroom CLI** exposed| `headroom proxy` | Run the Headroom proxy server | **native in container** || `headroom learn` | Learn from past tool-call failures | **native in container** || `headroom perf` | Summarize recent proxy performance | **native in container** |+| `headroom inspect` | Show original vs compressed content for recent requests | **native in container** || `headroom evals ...` | Run memory evaluation workflows | **native in container** || `headroom memory ...` | Inspect and manage stored memories | **native in container** || `headroom mcp ...` | Install, inspect, remove, or serve MCP integration | **native in container** |@@ -330,6 +331,30 @@ The command reads `${HEADROOM_WORKSPACE_DIR}/logs/proxy.log` (defaultsto `~/.headroom/logs/proxy.log` — see the[Filesystem Contract](filesystem-contract.md)).+## `headroom inspect`++Show the original vs compressed content for recent requests so you can *see*+what the compressor changed (not just the token counts). Useful for building+trust in compression and debugging quality regressions.++```bash+headroom inspect # inspect the most recent request+headroom inspect --last 5 # inspect the 5 most recent requests+headroom inspect --full # include unchanged messages+headroom inspect --format json # raw feed for piping into another tool+```++| Option | Default | Meaning |+|---|---|---|+| `--port` / `-p` | `8787` | Proxy port to query (env: `HEADROOM_PORT`) |+| `--last` | `1` | Number of most-recent requests to show |+| `--format` | `text` | `text` renders a highlighted diff; `json` emits the raw feed |+| `--full` | off | Include messages the compressor left unchanged |++`inspect` queries the running proxy's loopback `/transformations/feed` endpoint,+so the proxy must be started with `--log-messages` (or `--log-file`) for the+pre/post-compression snapshots to be captured.+## `headroom evals`Memory evaluation command group.