dshakes/distil

Other installs (curl, Homebrew, pipx, Windows): Install your way
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** — 18 presets: distil wrap -- for aider · claude · codex · gemini · copilot · goose · grok · kilo · kimi · vibe · opencode · openhands · qwen · cline · 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, and Gemini generateContent.
- **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.