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(troubleshooting): explain cache-mode default showing ~0 compression savings on the dashboard (#2248) (#2424)
Shubham Srivastava9cba64d89e16
diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdxindex 8136b609a..14552856a 100644--- a/docs/content/docs/troubleshooting.mdx+++ b/docs/content/docs/troubleshooting.mdx@@ -142,6 +142,27 @@ config.smart_crusher.min_tokens_to_crush = 100 # Default is 200</Tab></Tabs>+### Dashboard shows 0 compressed/saved tokens after upgrading to 0.31.0++**Symptom**: After upgrading from 0.27.0 to 0.31.0, the dashboard's compression / "Tokens Saved" figures read ~0, even though total token spend is the same or **lower** than before.++**Cause**: This is a default-mode change, not a regression. 0.31.0 ships the `coding` savings profile as the out-of-box default, and `coding` runs the proxy in **cache** mode (see [Savings profiles](/docs/proxy#savings-profiles)). Cache mode freezes the provider prefix and compresses only the newest turn *delta* — this deliberately avoids busting the provider's prompt cache. So the **compression** figure is small, and the savings shift to **cheaper prefix-cache reads** (cached input tokens are billed at a fraction of list price). On a short prompt there is little delta to compress, so the compression tile can read ~0 while your actual cost still drops.++**Where the savings show up**: Look at the **Prefix Cache Impact** panel and the **Compression vs Cache** tile on the dashboard — these reflect cache-read savings rather than per-request compression. The headline "Tokens Saved" tile only counts compression, so in cache mode it understates the real benefit.++**To get 0.27.0-style compression numbers back**: run the proxy in token mode, which prioritizes visible compression:++```bash+# Per run+headroom proxy --mode token++# Or pick a token-mode profile+HEADROOM_SAVINGS_PROFILE=balanced headroom proxy # ~70% target+HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy # ~90% target+```++Trade-off: token mode maximizes visible compression but rewrites prior turns, which can reduce provider prefix-cache hits — so raw compression goes up while cache-read savings go down. Cache mode is the default because, for long coding sessions, preserving the prefix cache usually wins overall.+## Claude Code context window is larger through the proxy**Symptom**: After pointing Claude Code at Headroom (`ANTHROPIC_BASE_URL`), `/context all`