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.

docs(proxy): document savings profiles section (#2091)

GUOHAO LIUd2fb5627097a
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx
index d2f521ab3..8747cd0a6 100644
--- a/docs/content/docs/proxy.mdx
+++ b/docs/content/docs/proxy.mdx
@@ -114,6 +114,64 @@ headroom proxy --codex-wire-debug
The old LLMLingua proxy toggles are no longer part of the CLI. Headroom's proxy compression path uses ContentRouter plus the current built-in compressors, including Kompress where applicable.
</Callout>
+## Savings profiles
+
+The proxy uses a **savings profile** to control compression behavior — which messages get compressed, how aggressively, and whether to prioritize provider prefix-cache stability or raw savings. Only the env var survives across related tools (`headroom wrap` passes it to the proxy it launches).
+
+```bash
+# Switch to a different profile
+HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy
+```
+
+### Built-in profiles
+
+| 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)** — 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). Protects the 2 most recent turns verbatim. Lossless-first with lossy fallback; tool search and cross-turn dedup enabled. This is the profile that `headroom wrap` uses.
+
+**`agent-90`** — Forces ML-based (Kompress) compression with a 10% keep-ratio, ignoring the lossless path. Compresses both user and system messages. Designed for non-coding or cost-sensitive workloads where maximum compression is the goal.
+
+**`balanced`** — Token-mode compression with a 30% keep-ratio. Uses the standard lossless pipeline (does not force Kompress). Protects 4 recent turns. A safe general-purpose profile.
+
+**`general`** — Token-mode compression for non-coding conversations. No turn protection (`protect_recent=0` — nothing code-positional to preserve) and does not compress user or system messages. Uses the standard lossless pipeline.
+
+### Profiles override CLI flags
+
+A profile's `proxy_mode` setting overrides the `--mode` flag. The `coding` profile sets `proxy_mode="cache"`, so `--mode token` has **no effect** when coding is active:
+
+```bash
+# These are equivalent — coding's cache mode always wins
+headroom proxy
+headroom proxy --mode token # --mode token is silently overridden
+```
+
+To run in token mode, switch to a profile that uses it:
+
+```bash
+HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy --mode token
+```
+
+### Extending a profile with env overrides
+
+Profile defaults are applied only when the corresponding env var is not already set. You can start from a named profile and override individual settings:
+
+```bash
+# Start from coding but force Kompress on
+HEADROOM_SAVINGS_PROFILE=coding HEADROOM_FORCE_KOMPRESS=1 headroom proxy
+
+# Start from balanced but lower the keep-ratio
+HEADROOM_SAVINGS_PROFILE=balanced HEADROOM_TARGET_RATIO=0.15 headroom proxy
+```
+
+### Custom profiles
+
+For permanent custom profiles, see the profile definitions in `headroom/agent_savings.py`. Each profile is an `AgentSavingsProfile` dataclass with fields for compression mode, target ratio, turn protection, and pipeline toggles.
+
## API endpoints
### `GET /health`