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.

3.2 KB
Raw Blame

Differential Network Capture

Headroom includes a containerized harness for comparing Claude Code traffic sent directly to Anthropic with traffic sent through a Headroom proxy. The harness uses mitmproxy in two isolated lanes, writes sanitized JSONL captures, and then generates Markdown/JSON reports with request route, header, body size, body hash, and JSON payload differences.

Run The Harness

cd docker/differential-network-capture
mkdir -p captures
export ANTHROPIC_API_KEY=...
export HEADROOM_PROXY_TOKEN='capture-secret'
export CLAUDE_PROMPT="Summarize this repository in one sentence."
docker compose up --build mitm-direct mitm-headroom-upstream headroom-proxy mitm-headroom-client
docker compose --profile run run --rm claude-direct
docker compose --profile run run --rm claude-headroom

The primary captures are written to:

  • docker/differential-network-capture/captures/direct.jsonl
  • docker/differential-network-capture/captures/headroom-client.jsonl

The Headroom lane also writes docker/differential-network-capture/captures/headroom-upstream.jsonl, which is the request Headroom forwards to Anthropic after proxy processing.

HEADROOM_PROXY_TOKEN is required for the Headroom lane. The capture addon adds it only to requests from mitm-headroom-client; direct and upstream captures never receive it. Keep this value private and use the same value when calling a deliberately public Headroom proxy.

The direct and upstream mitmproxy ports are published on loopback for local inspection. The client capture stays on the internal Compose network because it is an internal hop, so HEADROOM_CLIENT_MITM_PORT is intentionally not a supported setting.

By default only api.anthropic.com is logged. Override CAPTURE_INCLUDE_HOSTS with a comma-separated list to include other hosts.

Generate A Report

headroom capture network-diff \
  --direct docker/differential-network-capture/captures/direct.jsonl \
  --headroom docker/differential-network-capture/captures/headroom-client.jsonl \
  --output docker/differential-network-capture/captures/report.md \
  --json-output docker/differential-network-capture/captures/report.json

The report redacts sensitive header values and sensitive query values before comparison. Request bodies are captured so structural payload differences can be identified; keep the generated captures/ directory out of commits because it may contain prompts, tool outputs, and repository context.

For Claude Code deferred-tool investigations, the paired exchange table includes top-level Anthropic tools counts and serialized tool bytes. A jump from tools=0->N in the Headroom client lane is evidence that Claude Code eagerly materialized tool schemas before the request reached Headroom.

Custom Claude Invocation

Set CLAUDE_COMMAND to run the exact command under test in both lanes:

CLAUDE_COMMAND='claude -p "read README.md and summarize the proxy setup"' \
  docker compose --profile run run --rm claude-direct
CLAUDE_COMMAND='claude -p "read README.md and summarize the proxy setup"' \
  docker compose --profile run run --rm claude-headroom

Use CLAUDE_DIRECT_ARGS and CLAUDE_HEADROOM_ARGS when each lane needs different flags.