LeanCTX

LeanCTX is a local Rust binary that sits between a coding agent and the codebase, deciding what the agent reads and how much of it reaches the model. It works on two planes: a read path, where an MCP server and a shell hook compress file reads, command output, and search results before the agent sees them; and an opt-in wire path, where a local proxy compresses every request — system prompt, full history, and tool results — on its way to the model provider. It works with any MCP-compatible client, with auto-setup for more than 30 named agents.

File reads go through ten modes, from full content down to abstract-syntax-tree signatures and entropy-filtered views, using tree-sitter parsing for 27 languages. A target-density mode keeps the highest-entropy lines until a chosen fraction of the original tokens remains, and a signatures mode carries line spans so bodies can be pulled in on demand. Shell output is compressed by more than 95 patterns covering git, npm, cargo, docker, kubectl, and terraform. Compression is reversible by design: pruned or truncated payloads move to a content-addressed store with a deterministic handle, so the original bytes can be retrieved on demand.

Between sessions, a session-memory layer persists task state, facts, and decisions with structured recovery queries, and a knowledge graph holds temporal facts with validity windows plus episodic and procedural memory. A separate multi-edge property graph over imports, calls, exports, and type references drives impact analysis, related-file discovery, and search ranking, with hybrid retrieval combining BM25, embeddings, and graph proximity. Memory and graph export to a portable package file with SHA-256 integrity.

Cost and outcome tracking is built in rather than fed back into agent context. A per-event savings ledger records tokenizer details and a tamper-evident hash chain locally; cost per accepted outcome is the headline metric; budgets, roles, and throttling policies apply per agent; and a shadow mode compares treated runs against a configured baseline.

Addons extend the engine without a marketplace: a signed package carries either a sandboxed WebAssembly module that runs inside the context pipeline or a declaration that wires an external MCP server into the gateway. Signatures are re-checked locally against pinned module hashes, and every addon's output is scrubbed for secrets and tagged untrusted before it reaches the model. Measured on the project's own repository with the o200k_base tokenizer, across 50 files:

Read mode	Compression	Tokens	Quality
Raw read	0%	533.2K	100%
map	98.1%	8.0K	78%
signatures	96.7%	14.0K	96%
Cached re-read	~99.99%	~13	100%

Features

• Read modes: ten modes including full, map, signatures, line ranges, and target density, backed by tree-sitter parsing across 27 languages
• Shell compression: more than 95 output patterns for common development commands, with a raw escape hatch and a session-level off switch
• Request proxy: an opt-in local proxy that compresses every request, pins one reasoning-effort level across providers, and relocates volatile fields out of the cacheable prefix
• Session memory and knowledge graph: task state, facts, and decisions that survive a new chat, plus temporal facts with validity windows
• Property graph: multi-edge code graph over imports, calls, exports, and type references for impact analysis and ranked search
• Context packages and snapshots: portable bundles with SHA-256 integrity and git-anchored, signed snapshots that can be replayed or restored
• Savings ledger: an auditable per-event record of tokens, cost, and compression, kept locally
• Multi-agent tooling: agent registration, handoff bundles with context transfer, diaries, and shared state
• Addons: signed packages carrying a sandboxed WebAssembly module or an external MCP server declaration