LeanCTX is a context intelligence layer for AI coding agents, implemented as a single local Rust binary that optimizes how AI models interact with codebases. The project addresses a fundamental problem in agentic coding: AI agents waste significant token budgets on redundant file reads, uncompressed command output, and context that resets between chat sessions. By running locally alongside coding agents like Cursor, Claude Code, Copilot, and 30+ other platforms, LeanCTX reduces token consumption by 60–90% while maintaining full context fidelity.
The core functionality spans four dimensions of context management. First, compression handles input efficiency through ten distinct read modes including full content, map-based structural views, AST signatures, diff views, line ranges, and density-based filtering that keeps only high-entropy content. File reads that would normally cost 2000 tokens drop to approximately 13 tokens on cached re-reads. Shell output compression handles 95+ patterns specific to tools like git, npm, cargo, docker, kubectl, and terraform, reducing raw git status output from 800 tokens to 120 tokens. The compression is reversible by design—pruned content moves to a content-addressed store, allowing models to request original bytes back through multiple recovery paths including in-band markers and API endpoints.
Second, routing ensures appropriate fidelity per file read. An adaptive mode predictor learns optimal read modes per file type from past sessions, while an intent engine classifies query complexity to keep simple lookups cheap. Third, memory persistence solves the problem of context resetting between chats. Session memory survives across conversations, structured recovery queries persist through compaction, and a knowledge graph tracks temporal facts with validity windows. A property graph maintains multi-edge code relationships including imports, calls, exports, and type references to power impact analysis and search ranking. Critically, all memory stays local and portable—users can export sessions as .ctxpkg packages and move them across machines or models without vendor lock-in.
Fourth, the system provides proof and visibility through a signed, verifiable savings ledger and real-time dashboard showing token and USD savings. Users gain full visibility into context window budget allocation and can set budget controls. The project is distributed across multiple package managers: crates.io for Rust, npm for Node.js, AUR for Arch Linux, and Pi.dev. It includes 76 MCP tools and integrates with 30+ agents without requiring configuration changes. The README emphasizes that LeanCTX operates on a local-first, model-agnostic principle—users can swap between OpenAI, Anthropic, and Gemini without losing context or cache, keeping the context moat portable rather than locked into a vendor's billing model. The project's philosophy centers on owning context as a managed resource rather than renting it back from the model provider, with telemetry opt-in only and security as an explicit design concern.
