Distil

Distil measures what your coding agent's context tooling actually costs you — in dollars per solved task and in changed decisions: any compressor, your provider's own compaction, and its own.

uv tool install distil-llm && distil setup

Other installs (curl, Homebrew, pipx, Windows): Install your way

distil wrap -- claude      # run your agent through distil (or let `distil setup` make it always-on)

distil savings # what it saved you, from your own traffic distil doctor # if something looks off

distil audit --compressor anthropic-context-editing --cap-usd 1 # did it change what your agent does, and what it cost? (opt-in, capped)

distil audit report # helped, hurt, or can't tell yet, per compressor

Distil also compresses (lossless by default, every byte recoverable), and holds that compressor to the same measurements.

What the measurements say today (2026-10-06; every figure links to its artifact)

• On short coding tasks no compressor is shown to save money. SWE-bench Lite, 298 tasks, same model and grader: distil is at parity with no compression ($0.0393 vs $0.0387 per solved task). RTK looked 20.7% cheaper per task until we found that its arm read other arms' prompt cache; re-priced as a cold run it is −6.5% [−13.1%, +0.1%], not significant. Selective Context and Anthropic context editing are not cheaper. Headroom has not run there yet. Scoreboard →
• Long sessions: inconclusive. A 7-task long-horizon pilot (median 63–69 steps) shows no cost difference for distil or RTK; on the 6 tasks without one crashed attempt, distil cost 9.7% more than plain. Run →
• Why. An offline simulator that reproduces the provider's bill within 2.5% on runs it never saw finds that lossless policies change cost by less than 0.2%, and that lossy compression saves money only if the agent does not take extra steps to make up for what was removed. Measuring that is the next live A/B. Simulator → · Why RTK looked cheaper →
• On the maintainer's own metered Claude Code traffic (13,191 requests, September 2026) distil removed an estimated 8.3–9.2% of the bill, cache priced in, its own spend netted out (source, method). That is a same-trajectory estimate: it assumes the agent behaved the same, which is exactly what the A/B above has to check.

Why trust the measurements

• It doesn't break your prompt cache. Distil never rewrites bytes the provider still has cached; older context changes only once that cache has already expired. We shipped that bug once, measured what it cost, and made the rule an enforced invariant. The cache contract →
• Every compressed byte is recoverable. What distil folds away it keeps in a local store, and the agent gets a distil_expand tool to pull the exact original back mid-task. How the digest works →
• It's measured on a real bill, receipts included. Savings are counted per request and calibrated against the usage your provider actually bills; every request writes a hash-chained receipt you can verify. The same harness runs every other compressor, and when it found a flaw in its own head-to-head it published the correction. How it's measured →

And it tells you when it is hurting you. Shadow mode replays a sample of requests on the original and the compressed context and reports the difference per compression mode; when the digest's harm bound goes over budget, the proxy holds itself at lossless-only. Pointed at the providers instead, the same check found Anthropic's context clearing changed the agent's next action in 37 of 40 cases with every old tool result cleared (keep=0, synthetic corpus) (study).

Going deeper: what distil checks, and what it found when it pointed those checks at the providers' own compaction ↓

What it does

• Referee your context tooling — distil audit replays a capped sample of your own requests as a named compressor (distil, Anthropic context editing, OpenAI compaction, Headroom) would shape them and reports helped / hurt / can't tell yet, in billed dollars and in the agent's next action (ADR 0024). Offline, the SWE-bench outcome harness scores any arm on dollars per solved task, with each arm's prompt cache isolated; results are on the scoreboard.

• Wrap your agent — 19 presets: distil wrap -- for aider · claude · gemini · copilot · goose · grok · kilo · kimi · vibe · openclaude · opencode · openhands · qwen · cline · codex · cn · crush · droid · omp. Zero config, no code change. distil wrap --list prints every target, its mechanism and the provider shape it speaks.

• Run a proxy — point any base_url client at it. Python, TypeScript, any language, any framework. Sync proxy, async proxy, and a standalone gateway, with the same provider coverage in each: Anthropic Messages, OpenAI Chat Completions and the Responses API, Azure OpenAI, Gemini generateContent, AWS Bedrock InvokeModel and Google Vertex AI (Anthropic and Gemini). Which routes compress →
• Call it as a library — from distil import compress_messages in your own agent loop.
• Give your agent a recall tool — MCP server: it compresses its own output and gets the exact bytes back on demand.
• Framework hooks — LangChain · LangGraph · LiteLLM · Agno · Strands · AutoGen · LlamaIndex, in-process, no network hop — plus an ASGI middleware for any Starlette/FastAPI app that hosts its own LLM endpoint, and the npm package for the Vercel AI SDK. A strict-typed TypeScript SDK (sdk/typescript, ADR 0029) adds compress(messages, { provider }) for Anthropic and OpenAI shapes; like every in-process library it is lossless-only, byte-identical to the Python engine.
• Where a proxy can't reach — distil setup --hooks: Claude Code, Cursor (MCP output), Gemini CLI and Codex CLI compress tool output through their documented post-tool hooks. Lossless-only on a subscription unless you add --digest; every digest recoverable with distil expand . No proxy, no credentials touched. distil quota shows the rate-limit window it buys back. Hooks →
• Shape shell output at the source — distil sh -- (opt-in, ADR 0026) keeps every failure, error and summary line of a test run or git status verbatim and folds the passing-test noise behind a distil expand handle; distil hook install --shell makes Claude Code use it. On SWE-bench Lite transcripts test runs are rare, so it removes 0.06% of bash output there and stays opt-in. Shell →
• Same mechanisms on every provider — re-fetch verbatim, cold-point eviction, the edit-quote guard and census run on Anthropic Messages, OpenAI Chat and Responses, and Gemini; OpenAI and Gemini are priced, so savings and distil audit stop booking $0 there; the distil savings what-if replays Codex CLI and Gemini CLI sessions as well as Claude Code's. Parity matrix →
• VS Code Copilot Chat — its BYOK Custom Endpoint can point at a distil proxy: distil setup --vscode.
• Keep a span verbatim — … in a prompt or tool output is never compressed.
• Keeps MCP tool search on — distil wrap -- claude keeps Claude Code's MCP tool search switched on, which Claude Code otherwise turns off behind a proxy, so unused connectors stay deferred instead of riding along on every turn. Verified live on 1.54.0 (2026-09-25): tools_deferred of 4–5 on every request, tool payload 9,733 tokens, prompt-cache reads intact. (ADR 0013)
• Real code skeletons — pip install 'distil-llm[code]' adds tree-sitter parses for Go, Rust, Java, C/C++, Ruby and TS/JS. Code skeletons →
• See what it did — live status line, session dissect, per-request headers, OTel spans, Prometheus metrics.

uv tool install distil-llm && distil setup    # detects your agent + billing, wires everything

Not sure which of those you want? Two questions pick your mode → — plain language, honest savings ranges, no jargon.

Will it save you money? On metered billing (an API key) it cuts the tokens you send —

an estimated 8.3–9.2% of the bill on the maintainer's traffic, if the agent behaves the same. Whether that shows up as a

lower bill depends on the workload: on short SWE-bench tasks the net cost effect measured cost-neutral, and the

long-session pilot (7 tasks) is inconclusive. On a flat-rate Pro/Max subscription there is