lean-ctx Deep Dive: Your AI Coding Assistant Is Silently Burning 70% of Its Tokens
TL;DR: Every time Cursor or Claude Code reads a file or runs a command, there's an invisible token tax. Three MCP servers' tool definitions can eat 40–50% of the context window; a single npm run build failure pushes 847 lines of errors into the prompt. lean-ctx inserts a Rust-written "cognitive compression layer" between you and the AI: cached file re-reads cost ~13 tokens, shell output is automatically compressed by ~95%, and cross-session memory is never lost. But the project is only weeks/months old, and early versions had state-loss bugs.
Key points
- MCP tool schemas are a context black hole. Stacklok measured ~8,200 tokens for GitHub (23 tools), ~5,100 for Slack (15), ~11,400 for a database server (31). Five servers / 87 tools means full schemas ship with every request regardless of relevance. A test where the user only said "hello" injected 114 tools' metadata — 46,800 tokens. Merge CTO Gil Feig: "tool metadata occupies 40–50% of usable context."
- Shell output is a dynamic black hole.
npm run buildfailures (847 lines),git log -50,docker psall dump raw output into prompts when the AI may only need one fact. - Session cold starts waste tokens. Close your IDE, reopen, and the AI re-reads
package.json,tsconfig.json, etc. from scratch — same files, same token cost, no memory. - Author: Yves Gugger, Zurich, Switzerland
- Repo: https://github.com/yvgude/lean-ctx
- Traction: 1,800+ stars (~4 months), 190+ forks, 181 releases, 29+ supported AI agents
- Positioning: a lightweight "Lean Cortex" — a cognitive layer managing every token between code and AI
- File reads in 10 modes:
full,map,signatures,diff,lines:N-M, etc. - Shell output: 56+ compression patterns, 270 rules (git: 95%+ savings; npm/cargo builds: 90%+; docker: 80%+; kubectl/terraform: 85%+)
- Tree-sitter ASTs for structural understanding of 21 languages 2. Memory — sticky value
- CCP (Cross-Context Protocol): persists tasks, facts, and decisions across sessions; injects a memory summary on session start. This is the differentiator vs. competitors.
- Knowledge graph with temporal facts (with validity windows), episodic memory, and procedural memory
- Property graph tracking
import/call/export/type_refedges for impact analysis without grepping the codebase
3. Governance & Observability — enterprise value
- Context Manager: browser dashboard with real-time token tracking per tool call and compression ratios
- Budgets & SLOs: per-agent/per-role token budgets with throttling/alerting
- Context Proof: 4-layer cryptographic verification that compressed content wasn't tampered with
- State-loss bugs in early versions: CCP memory not recovered after session crashes, property-graph incremental updates failing on large repos, and project-identity conflicts in Docker (missing
.lean-ctx-idmerging data). - 181 releases in ~4 months means fast iteration but unstable APIs; some churn is likely agent-compat fixes (Claude Code truncates MCP server instructions to 2048 chars; Cursor/Windsurf rule formats differ, etc.).
- Good fit: mid-to-large repos (50+ files), shell-heavy workflows, long multi-session projects, teams needing token visibility.
- Poor fit: single-file scripts, raw log analysis needing unfiltered output, one-off prompts.
- Learning curve: configuring read modes, compression rules, CCP memory lifecycles, and budgets — this is infrastructure you operate, not install-and-forget.
- Privacy of CCP memory: project A's memories could leak to project B if misconfigured; sensitive facts (temporary API keys, internal decisions) persist to disk; shared instances raise access-control issues. Docs mention "40+ security hardening fixes" (v3.5.16), but privacy remains a long-term challenge.
- 29-agent compatibility burden: every agent update may break MCP behavior, requiring follow-up releases.
- Project: https://github.com/yvgude/lean-ctx
- Docs: https://leanctx.com/docs/getting-started
- MCP token bloat: https://thenewstack.io/how-to-reduce-mcp-token-bloat/
- MCP Optimizer (ToolHive): https://stacklok.com/blog/cut-token-waste-from-your-ai-workflow-with-the-toolhive-mcp-optimizer/
- Dynamic Toolsets (Speakeasy): https://www.speakeasy.com/blog/how-we-reduced-token-usage-by-100x-dynamic-toolsets-v2
- MCP token wars (Juejin): https://juejin.cn/post/7621644374128640027
What lean-ctx is
Architecture (3 layers)
1. Compression — immediate value
Key design philosophy: not selective tool loading (like MCP Optimizer or Dynamic Toolsets), but "compress what's loaded, cache what's read, filter what's output."
Measured results
| Scenario | Original | With lean-ctx | Savings | |---|---|---|---| | First file read | depends on size | best-of-10 modes | 60–95% | | Cached re-read | depends on size | ~13 tokens | ~99% | | Shell output (git/npm etc.) | raw | pattern-compressed | 60–95% | | AST queries | search + read | property graph direct | 80–90% |
Worked example — a typical coding session (~100K tokens raw: 10 file reads ~50K, 20 shell commands ~30K, tool schemas ~20K) drops to ~41K with lean-ctx (59% saved). Combining with MCP Optimizer (schema 20K→4K) plus lean-ctx (results 60K→20K) yields ~76% total savings. Note: vendor-claimed savings across tools are not directly comparable since each optimizes different objects (schemas vs. outputs vs. conversation history).
Competitive landscape
| Approach | Idea | Memory | Governance | |---|---|---|---| | context-mode (~12K stars) | "code mode": LLM writes code to call tools | No | No | | MCP Optimizer (ToolHive) | smart schema filtering | No | No | | Dynamic Toolsets (Speakeasy) | on-demand schema loading + semantic search | No | No | | Claude Praetorian | structured incremental snapshots | Limited | No | | lean-ctx | 3-layer compression + memory + governance | CCP cross-session | Dashboard + budgets |
These are largely complementary: many tools (>20) → schema filtering; frequent tool calls → lean-ctx result compression.
A cold shower: a very young project
Open questions
Conclusion
MCP made AI agents' ability to connect to the world explode, but every connection silently drains the context window. lean-ctx's core insight: token efficiency is an engineering gap, not a model problem. How files are read, how command output is compressed, how session memory is stored, how spend is made visible — all are solvable engineering problems, and lean-ctx packages them into a single Rust binary, one-command install, working across 29 agents. If you burn tens of thousands of tokens daily on redundant reads and verbose output, it's worth trying. If you occasionally write a single-file script, it's probably overkill.