Everything ContextPilot does, and doesn't do yet.
This page covers the essentials. For exhaustive detail, read the source: the README and the docs folder are the source of truth and update the moment the code does.
Four surfaces, one engine.
Pick whichever matches how you already work. All four run the same compression pipeline underneath.
Drop-in wrapper. One call, every existing call stays unchanged.
For Claude Code, GPT Codex, Aider. Install once, runs on every login.
Claude Desktop and Claude Code call it as a tool, on its own terms.
AST-based, not regex. For codebases with 50+ existing LLM calls.
Works with zero config. Tune it if you want to.
Drop a contextpilot.yaml in your project root, or set environment variables. Full field-by-field reference is in the repo's docs/configuration.md.
Nothing, unless you turn it on. Even then, not content.
A plain answer for anyone deciding whether to point this at real code.
Runs in your own process, in memory. Your prompt text goes to the LLM provider you already use and nowhere else. Not to a ContextPilot server, there isn't one in this path.
On by default. Writes token counts, latency, and quality scores to a file on your own disk (~/.contextpilot/events.jsonl). No prompt or response content in the schema, ever. Nothing sent over the network.
Opt-in only, requires an explicit API key. As of now, this service isn't live yet, setting a key is a safe no-op, not a data leak. This section will change the day that changes.
Full data-handling policy, proxy trust model, and vulnerability reporting: SECURITY.md.
What token reduction actually does to your bill.
Tokens are what we measure. They are not what you are billed for once prompt caching is involved.
Provider prompt caching is a strict byte-prefix match: cached reads bill at roughly 0.1x the base input price, cache writes at 1.25x, and the first differing byte invalidates everything after it.
Without caching (one-shot calls, prefixes that never repeat), token reduction translates roughly to cost reduction. With caching (multi-turn chat, coding agents, anything resending a conversation), caching already handles your repeated prefix at 0.1x, so compression saves far less on top. A compressor that rewrites earlier bytes invalidates the cache and makes the bill worse: it has to remove roughly 90% of tokens just to break even.
Measured against our own engine on a 40-turn synthetic agent transcript with a simulated prefix cache: 0.3.x cut 76.3% of tokens and cost 87.5% more than sending payloads unchanged. 0.4.0 cuts 63.8% and costs 8.7% less. The engine now keeps the forwarded payload byte-stable and runs a cost gate that falls back whenever compression would be a net loss.
That benchmark uses a simulated cache built from published pricing. It has not yet been validated against live API responses, which is why the headline number on this site is about tokens, with a guarantee about cost, rather than one blended figure.
One consequence worth knowing: the cost gate has to assume whether your workload is cached. The proxy and library wrapper assume it is, because they serve repeated conversations. A one-shot contextpilot.compress() call assumes it is not, because there is no prefix to preserve. If your usage does not match the assumption, set assume_cached explicitly.
What this doesn't do yet.
Written for whoever is deciding whether to adopt this, not to make it look better than it is.
- →Compression scoring is TF-IDF based, not a trained model. Lighter and faster, at some cost to accuracy versus learned approaches like LLMLingua-2.
- →Messages whose content is a block list (tool calls, tool results, images) are analyzed but forwarded byte-identical. That is deliberate, rewriting them would break provider prompt caching, but it means no savings inside large tool results yet.
- →Shadow A/B testing runs in the library wrapper only. The proxy and MCP surfaces never hold both responses, so they don't shadow.
- →No Google Vertex AI adapter yet, OpenAI and Anthropic only.
- →The 100K-token performance budget is a target, not yet independently verified at that scale by an automated benchmark.
Full list, plus pros, cons, and what to avoid: docs/limitations.md.