Which mode? Start with two questions

distil has several ways to run, and the names are jargon (“wrap”, “hook”, “proxy”, “MCP”). You don’t need to learn them. Two questions pick your mode, and the second one matters more than the first.

A decision tree. First question: how do you pay? Pay-per-use with an API key leads to distil wrap, which sits invisibly between your assistant and the provider and cuts the bill. A flat monthly subscription leads to distil hook install, which lets Claude Code compress its own tool output and buys back rate-limit headroom. Second row: a coding assistant means wrap or hook, an app you are building means proxy or library, Claude Desktop means the MCP server, a whole team means the gateway. Footer: savings depend on the shape of your tool output, not the mode — JSON 28 to 33 percent, repeated log lines up to 99 percent, prose about 0 percent.

Don’t want to read any of this? Run distil onboard. It detects your operating system, which assistants you have installed, and whether you’re on a subscription or an API key — then prints the exact commands for your setup, in order. This page is the same reasoning, written out.

Question 1 — how do you pay?

This decides what you save, not how much.

You pay	What runs out	What distil buys you
Per use — an API key, a bill each month	Money	A smaller bill. Fewer tokens sent means fewer tokens charged.
Flat monthly — Pro or Max subscription	Your usage limit	More room before you hit the wall. The bill is fixed; the window isn’t.

We used to say a subscription got “context and latency, not the bill.” A reader pointed out that was wrong — running out of quota is a cost — and they were right. That correction has its own page.

Question 2 — what are you actually running?

🖥️ A coding assistant in a terminal

Claude Code, Codex, Gemini CLI, Aider, Goose, OpenCode and friends.

On an API key — put one word in front of your normal command:

distil wrap -- claude

Nothing about how you work changes. distil sits in between, invisibly, and shrinks what gets sent. This is the mode most people want.

On a subscription — a different mechanism entirely:

distil hook --install     # then restart Claude Code

Claude Code compresses its own tool output before reading it, using an extension point Anthropic built and documents. Nothing sits in between and nothing touches your login — which matters, because Anthropic’s terms restrict intercepting subscription traffic, and distil won’t risk your account for a few percent. Claude Code only, for now: Codex doesn’t allow output rewriting and Gemini only partly does.

🧱 An app you’re building

Two options, same engine.

Proxy — run a small local service and point your app’s base URL at it. Works with any language or framework, no code change beyond one config line.

Library — from distil import compress_messages, called exactly where you want it. No background service, no network hop, but you write the code.

Already using LangChain, LangGraph, LiteLLM, Agno or Strands? There are drop-in hooks for those — see Integrations.

💬 Claude Desktop

The desktop app can’t be wrapped or proxied. What works is the MCP server: it hands the assistant two tools — shrink this, and give me the original back.

claude mcp add distil -- distil mcp

The assistant decides when to use them, so this is occasional rather than automatic. Worth it when you routinely paste or read very large documents.

🏢 A whole team

The gateway is one shared service everyone routes through, with per-team accounting and keys. See Deploy & Security.

How much will it actually save?

Here is the part most tools won’t tell you: the mode barely matters. What your tools print matters enormously.

What your assistant reads	Typical saving
Config files, dependency lists, API responses (JSON)	28–33%
Logs where the same line repeats	up to 99%
Ordinary prose, documentation, chat	~0%
Logs where every line differs, `git log`	~0%

Two rules of thumb:

A short session that never reads a big file will show close to 0%. That is the tool working correctly, not failing. There was nothing to compress.
Long sessions that re-read the same large files are where it pays. The same content gets re-sent every turn; that’s the waste distil removes.

Our own honesty check. On distil’s internal test corpus, the new hook saves 0.00% — that corpus contains no JSON and no repeated lines. We publish that number next to the good ones, because quoting only the flattering fixtures is exactly what we criticise other compressors for.

How do you know it didn’t break anything?

Every compressor claims savings. distil is built around a second question: did your assistant still do the same thing? It answers that one with measurements, not assurances.

Command	Tells you
`distil savings`	Tokens and dollars saved, calibrated against what you were actually billed
`distil quota`	Your subscription windows, live — so “we saved you room” is checkable
`distil shadow-stats`	How often a compressed request produced a different decision than the uncompressed one
`distil dashboard`	All of it, in a browser
`distil doctor`	Whether your setup is actually routing (the most common failure is silent)

One-line cheat sheet

You are…	Run this
Coding with an API key	`distil wrap -- claude`
Coding on a Pro/Max subscription	`distil hook --install`
Using Claude Desktop	`claude mcp add distil -- distil mcp`
Building an app	`distil proxy` or the library
Running a team	`distil gateway`
Not sure	`distil onboard`

Everyone, afterwards: distil savings on an API key, or distil quota on a subscription — to see whether it helped you, rather than taking our word for it.