Entroly – Auditable, reversible context compression for AI coding tools

What it does (plain‑English)

Entroly sits between your editor / IDE and a large‑language‑model (LLM) provider. Before a request is sent it:

• Selects the most useful pieces of code, docs, or other files that fit inside a token budget you set.
• Compresses the rest, but keeps a receipt – a cryptographic hash that points to the exact bytes that were omitted.
• Records what was kept, what was dropped and why, so you can later prove the model saw exactly the context you intended. If the model later needs the omitted material (e.g., a long session runs out of context), Entroly can recover the original bytes from the receipt without contacting the provider again.

Why you might care

Goal	How Entroly helps
Save money – fewer tokens = lower API bill	It trims the prompt to the most relevant fragments while staying inside a budget.
Never lose evidence – you can always get back what was dropped	Receipts are content‑addressed (hash‑based) and point to the exact original bytes stored locally.
Auditability – prove what was sent to the model	Every run produces a receipt that can be inspected (entroly verify-claims).
Zero code changes – works with existing tools	It hooks into supported editors (VS Code, Cursor, Claude Code, etc.) or runs as a local proxy that any app can point to.

How you use it

Situation	Command(s)	Result
Python user – want the full feature set	pip install -U entroly && entroly go	Starts a local proxy + dashboard; point your app at the displayed URL.
Node / WASM fan	npm install -g entroly && entroly init	Gives you a CLI and MCP path; you can still call the Python proxy for the richer SDK.
Rust‑only binary	cargo build --release --bin entroly-rs --features proxy	One self‑contained executable, no Python/Node needed.
VS Code / Claude Code / Cursor	Install the Entroly extension / run entroly activation install --host <host>	A prompt hook runs automatically before the model plans; check it with entroly activation status.
Programmatic use	from entroly import compress, compress_messages, optimize	Call the library directly to compress a response, a list of messages, or arbitrary fragments.
Run a quick sanity check	entroly verify-claims && entroly simulate	Runs locally, no API key, shows token‑saving numbers for your own repository.

Core concepts & terminology

• Receipt – a cryptographic hash (e.g., sha256:…) that uniquely identifies the omitted bytes. The receipt lets you later entroly recover <hash> to get the exact original content back.
• MCP (Model‑Control‑Plane) – the integration layer that intercepts a request, runs Entroly’s selection/compression, and forwards the reduced prompt to the provider.
• Proxy – a local HTTP server (localhost:9377 by default) that mimics the OpenAI/Anthropic/Gemini endpoint. Point your OPENAI_BASE_URL, ANTHROPIC_BASE_URL, etc. at it to enable compression for any client.
• Simulation (entroly simulate) – runs the selection algorithm on a sample query without contacting a model, reporting how many tokens would be saved and what the retention score would be.
• Repair / self‑heal – optional step that downloads a native‑engine binary if the fast‑path engine is missing.

Benchmarks (as reported in the repo)

Benchmark (run with gpt‑4o‑mini)	Baseline accuracy	Entroly accuracy	Retention	Token savings
NeedleInAHaystack	100 %	100 %	100 %	99.5 %
LongBench (HotpotQA)	64 %	66 %	103 %	85.3 %
Berkeley Function Calling	100 %	100 %	100 %	79.3 %
SQuAD 2.0	80 %	72 %	90 %	43.8 %
GSM8K	85 %	85 %	100 %	pass‑through

Retention = (Entroly accuracy ÷ Baseline accuracy) × 100 %. Positive numbers mean the model performed just as well despite a smaller prompt; negative numbers (e.g., SQuAD 2.0) show a trade‑off.

Integration ecosystem

Entroly provides adapters for many popular stacks:

• SDKs – OpenAI, Anthropic, LangChain, LiteLLM, Vercel AI SDK, etc.
• IDE / MCP hosts – VS Code, Cursor, Claude Code, Kiro, OpenClaw, OpenCode, Grok, etc.
• Agent frameworks – CrewAI, AutoGen, Strands Agents, Agno, etc. The docs contain a full matrix (docs/integration-hub.md). Using an adapter does not automatically guarantee token savings; the request must travel through the Entroly proxy or verified prompt hook.

Getting started checklist

1. Install the runtime you prefer (Python pip install -U entroly is the most complete).
2. Run a local sanity check: entroly verify-claims && entroly simulate inside a repo you care about.
3. Activate the integration you need – e.g., entroly activation install --host vscode or point your API base URL at http://localhost:9377.
4. Inspect receipts after a request with entroly value --json or entroly activation status --json.
5. Recover any omitted fragment with entroly recover <hash> --out restored.json.

License & community

• License: Apache 2.0
• Stars / CI: actively maintained (GitHub stars badge, CI badge shown in README).
• Contributions: welcome – see CONTRIBUTING.md for development setup, style guide, and test instructions.
• Downloads: PyPI, npm, Homebrew, Docker images are all provided.

---

TL;DR

Entroly is a local‑first, plug‑and‑play layer that lets you shrink LLM prompts, keep a verifiable record of what was dropped, and pull that data back later – all without changing your existing code. It works with many editors, SDKs, and agent frameworks, and the repo includes benchmarks, a CLI, a Python library, a Rust binary, and a VS Code extension.