Getting Started

Four steps: install, set up, run your agent, see what it saved. No code change.

Want to see what your agent costs you before installing anything? uvx --from distil-llm distil savings reads your Claude Code transcripts, read-only. distil --help shows only the four front-door commands (setup, wrap, savings, doctor); distil --help-all lists everything else.

1. Install

uv tool install distil-llm

No uv? The one-line installer gets it first, then runs the line above:

curl -LsSf https://dshakes.github.io/distil/install.sh | sh

Or brew install dshakes/tap/distil. On Windows: powershell -ExecutionPolicy ByPass -c "irm https://dshakes.github.io/distil/install.ps1 | iex". The package is distil-llm; the command is distil. Other formats (pipx, Docker, pip, npm, a single file) and install troubleshooting: Install your way.

2. Set up

distil setup

Detects your agent and how you pay (an API key, or a Pro/Max subscription), picks the mode that fits, wires the savings status line into Claude Code, and offers to make distil always-on so you never have to type wrap. Not sure which mode you want? Two questions pick it.

3. Run your agent

distil wrap -- claude

Routes that session through distil. Same pattern for codex, gemini, aider and the rest; distil wrap --list prints every agent it can reach, and the ones it cannot. For Claude Code it also keeps MCP tool search switched on, which Claude Code otherwise turns off behind a proxy. Using an IDE agent or your own SDK code? See Integrations.

4. See what it saved

distil savings

What distil saved on your traffic, calibrated against the usage your provider bills. Something looks off? distil doctor checks the wiring.

What to expect. On an API key distil cuts the tokens you are billed for; on a subscription the saving is rate-limit headroom. Fewer tokens is not automatically a lower bill: on short SWE-bench tasks no compressor, distil included, is shown to save money end to end (scoreboard), so run distil savings on your own traffic. For reference, the maintainer's own Claude Code traffic (13,191 requests, September 2026) came out an estimated 10.2% cheaper, cache included, before distil's own expand re-queries and shadow replays were netted out; about 9% (8.3–9.2%) net of them, assuming the agent behaved the same (how) (data). Savings come from large, repetitive tool output, so a short session that never reads a big file showing near zero is the tool working, not failing.

CLI reference — every command and flag.
Cache contract and the proof — why the number holds up.
Library API — compress inside your own agent loop.
Adoption — the opt-in census (off unless you turn it on).
Leaving? distil offboard removes everything distil wired, then prints the uninstall command.

Getting Started

1. Install

2. Set up

3. Run your agent

4. See what it saved

Next