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
docs: clarify Target savings metric is % of new input tokens (#4485)
yi111b0d62f1d6dbf
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex e2912b79e..819328dad 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -112,10 +112,10 @@ headroom proxy --mode cache| Profile | Target savings | Mode | Notes ||---------|----------------|------|-------|-| `coding` | emergent (~50%) | `cache` | **Default.** Delta-only compression at ~0 prefix-cache busts; never lossy-compresses file reads. |-| `balanced` | ~70% | `token` | Moderate compression with structural compaction. |-| `agent-90` | ~90% | `token` | Aggressive; pins a `0.10` keep-ratio and forces Kompress. |-| `general` | emergent (~60%) | `token` | Non-coding workloads. |+| `coding` | ~50% of new input tokens (emergent) | `cache` | **Default.** Delta-only compression at ~0 prefix-cache busts; never lossy-compresses file reads. Whole-request and lifetime ratios are much lower in cache mode. |+| `balanced` | ~70% of new input tokens | `token` | Moderate compression with structural compaction. |+| `agent-90` | ~90% of new input tokens | `token` | Aggressive; pins a `0.10` keep-ratio and forces Kompress. |+| `general` | ~60% of new input tokens (emergent) | `token` | Non-coding workloads. |An unrecognized `HEADROOM_SAVINGS_PROFILE` value logs a warning and falls back to `coding` (the same default an unset variable resolves to) — the proxy never fails to start over a bad profile name. `balanced` is used only as a last-resort fallback when the runtime has no `coding` entry at all (old-runtime/new-client version skew). See `headroom/agent_savings.py` for each profile's full set of knobs.@@ -194,10 +194,10 @@ HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy| Profile | Target savings | proxy_mode | force_kompress | Best for ||---------|---------------|------------|---------------|----------|-| `coding` (default) | ~50% (emergent) | `cache` | No | Coding agents — preserves Anthropic prefix-cache stability |-| `agent-90` | 90% | `token` | Yes | Non-coding, cost-sensitive, or high-volume workloads |-| `balanced` | 70% | `token` | No | General-purpose moderate compression |-| `general` | ~60% (emergent) | `token` | No | Non-coding chat, little code in context |+| `coding` (default) | ~50% of new input tokens (emergent) | `cache` | No | Coding agents — preserves Anthropic prefix-cache stability. Whole-request and lifetime ratios are much lower in cache mode. |+| `agent-90` | ~90% of new input tokens | `token` | Yes | Non-coding, cost-sensitive, or high-volume workloads |+| `balanced` | ~70% of new input tokens | `token` | No | General-purpose moderate compression |+| `general` | ~60% of new input tokens (emergent) | `token` | No | Non-coding chat, little code in context |**`coding` (default)** — Optimizes for coding-agent workloads with Anthropic. Uses **cache mode** (`proxy_mode="cache"`): compresses only the newest delta in each turn so the provider's prefix-cache is never busted. User messages are compressed, system prompts preserved (hottest cache). `protect_recent` is `0` — in cache mode the delta already *is* the newest turn, so a turn-count guard would suppress the only thing cache mode compresses; byte-exact fidelity instead comes from `protect_reads=True` (file reads are never lossy-compressed). Lossless-first with lossy fallback; tool search and cross-turn dedup enabled. This is the profile that `headroom wrap` uses.