lean-ctx

<div align="center"> <pre> ██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗ ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝ ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗ ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ </pre>

Control what your AI can see.

LeanCTX — AI Value Gate for AI Coding Agents

LeanCTX — short for Lean Context — is an AI Value Gate and context engineering layer for AI coding agents. It runs locally alongside your coding agent, helping it read repositories, run development commands, and send focused context to the model: it understands the task, routes the right context, compresses what it sends, and tracks the cost and outcome of that work. Savings depend on the workload and enabled modes; the local savings ledger and Shadow Mode show the measured result against a comparable baseline. Zero config required. Local-first.

| Problem | With LeanCTX | |---------|-------------| | Repeated file reads resend unchanged content | Cached re-reads return a compact deterministic reference | | Raw development commands include repetitive noise | Command-specific compression preserves salient output | | Every turn re-sends the whole history | Proxy compresses each request, prompt-cache-safe | | Context resets every chat | Session memory persists across chats | | No visibility into context usage | Real-time dashboard + budget control |

---

<p> <a href="https://github.com/yvgude/lean-ctx/stargazers"><img src="https://img.shields.io/github/stars/yvgude/lean-ctx?style=social" alt="GitHub Stars"></a>&nbsp;&nbsp; <a href="https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml"><img src="https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml"><img src="https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml/badge.svg" alt="Security"></a> <a href="https://crates.io/crates/lean-ctx"><img src="https://img.shields.io/crates/v/lean-ctx?color=%23e6522c" alt="crates.io"></a> <a href="https://crates.io/crates/lean-ctx"><img src="https://img.shields.io/crates/d/lean-ctx?color=%23e6522c" alt="Downloads"></a> <a href="https://www.npmjs.com/package/lean-ctx-bin"><img src="https://img.shields.io/npm/v/lean-ctx-bin?label=npm&color=%23cb3837" alt="npm"></a> <a href="https://aur.archlinux.org/packages/lean-ctx"><img src="https://img.shields.io/aur/version/lean-ctx?color=%231793d1" alt="AUR"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a> <a href="https://discord.gg/pTHkG9Hew9"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord"></a> <a href="https://x.com/leanctx"><img src="https://img.shields.io/badge/𝕏-Follow-000000?logo=x&logoColor=white" alt="X/Twitter"></a> <img src="https://img.shields.io/badge/Telemetry-Opt--in%20Only-brightgreen?logo=shield&logoColor=white" alt="Opt-in Telemetry"> </p> <p> <a href="https://leanctx.com">Website</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://leanctx.com/docs/getting-started">Docs</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#get-started-30-seconds">Install</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#real-world-scenarios">Scenarios</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#demo">Demo</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#benchmarks">Benchmarks</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="cookbook/README.md">Cookbook</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="SECURITY.md">Security</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="CHANGELOG.md">Changelog</a> </p> </div>

---

Control what your AI can see — and what it costs. LeanCTX is an AI Value Gate for coding agents: it understands tasks, routes and compresses context, remembers what it learns, and measures cost against accepted outcomes.

Token savings are the receipt. Intelligence is the product. Works with Cursor, Claude Code, Copilot, Windsurf, Codex, Gemini and 30+ other agents — no config needed.

<p align="center"><strong>See it in action:</strong></p> <table> <tr> <td align="center" width="33%"> <img src="assets/leanctx-demo.gif" width="320" alt="Map-mode file read + compressed git output demo"> <br/> <strong>Read + Shell</strong> <br/> Map-mode reads + compressed CLI output </td> <td align="center" width="33%"> <img src="assets/leanctx-gain.gif" width="320" alt="lean-ctx gain live dashboard demo"> <br/> <strong>Gain (live)</strong> <br/> Tokens + USD savings in real time </td> <td align="center" width="33%"> <img src="assets/leanctx-benchmark.gif" width="320" alt="lean-ctx benchmark report demo"> <br/> <strong>Benchmark proof</strong> <br/> Measure compression by language + mode </td> </tr> </table> <p align="center">_{All GIFs are generated from reproducible VHS tapes in <code>demo/</code>.}</p>

Why developers use LeanCTX

• Longer useful coding sessions — less context waste = more room for actual code reasoning
• Lower API costs — reduce repeated context on reads and shell output; inspect the local savings ledger and Shadow Mode baseline for your workload
• No more "I already showed you this file" — session memory persists across chats
• Works with your existing setup — one lean-ctx setup command, no config changes needed
• Full visibility — see exactly where your context window budget goes
• Model-agnostic & yours — swap OpenAI/Anthropic/Gemini freely; your context and memory stay local and portable, never locked in a vendor's black box

---

<p align="center"> <strong>Saves you tokens?</strong> <a href="https://github.com/yvgude/lean-ctx">Give it a star</a> — it helps others discover LeanCTX. </p>

---

Why now — own your context

Models are converging on commodity. The durable edge isn't which model you call — it's your context: what your agents read, what they remember, and what you can prove. And the layer that optimizes and owns that context can't come from the vendor that bills per token or keeps your memory in a black box — it has to sit on your side.

That's the shift behind "agent entities" that live in your chat and remember your company (Claude in Slack, ClickUp Brain): a context login, not a model login — you end up renting your own company knowledge back. LeanCTX is the opposite layer. It keeps the moat yours: local-first, portable (.ctxpkg), and model-agnostic — swap OpenAI, Anthropic or Gemini without losing context or cache. Own your context; don't rent it back.

---

What it does — five capabilities of an AI Value Gate

LeanCTX treats context and AI spend as managed resources, not afterthoughts. One binary covers the capabilities that decide how well an AI agent performs:

1. Context Compression — input efficiency

Your AI agent reads files and runs commands. LeanCTX compresses both automatically.

• Workload-specific token reduction on eligible context, with recovery paths and a local Shadow Mode baseline for measurement

• File reads: 10 read modes (full, map, signatures, diff, lines:N-M, density:X, …) — cached re-reads cost ~13 tokens

• Target density (density:0.4): SDE-style budget compression — keeps the highest-entropy lines until ~40% of the original tokens remain, deterministic

• JIT disclosure: signatures carries line spans and points at lines:N-M for targeted expansion — outline first, bodies on demand

• Shell output: 95+ shell-output patterns compress git, npm, cargo, docker, kubectl, terraform and more (270 passthrough rules)

• Tree-sitter AST: structural understanding for 27 languages — not just text compression

• Reversible by design (CCR): compression never discards content — pruned or truncated payloads move to a content-addressed store with a deterministic handle, so the model can pull the original bytes back on demand via ctx_expand, ctx_retrieve, an in-band marker, or GET /v1/references/{id}. Five recovery paths →

2. Intelligent Triage — task understanding

Not every task or file needs the same depth. LeanCTX classifies the task, then sends the signal rather than the noise.

• 10 read modes: from full content down to AST signatures and entropy-filtered views
• Adaptive ModePredictor: learns the optimal read mode per file type from past sessions
• IntentEngine: classifies query complexity so simple lookups stay cheap

3. Knowledge Routing — cross-source context

Relevant code, sessions, and connected sources become focused context instead of a larger prompt.

• Session memory (CCP): persist task/facts/decisions across chats — structured recovery queries survive compaction
• Knowledge graph: temporal facts with validity windows, episodic + procedural memory
• Property Graph: multi-edge code graph (imports, calls, exports, type_ref) powers impact analysis and search ranking
• Yours, not the vendor's: memory stays local and portable — export it as a .ctxpkg package and move it across machines or models, instead of locking it in a vendor's black box

4. AI Value Gate — cost and outcome tracking

Performance is the cost of a useful result, not just speed. LeanCTX records costs and outcomes locally; CPAO (Cost per Accepted Outcome) is the north-star metric for comparing useful AI work.

• Context Manager: browser dashboard with real-time token tracking, compression stats, utilization gauge
• Budgets & SLOs: profiles, roles, per-agent budgets, and throttling policies
• Context Proof (ctx_proof, ctx_verify): 4-layer verification engine with CI drift gates

5. Shadow Recommendations — savings proof

Shadow Mode compares LeanCTX treatment with a configured baseline without changing the active workflow. Its reports show cost, tokens, CPAO, and whether quality held, then recommend savings only when the comparison supports them.

Cost Intelligence

LeanCTX automatically tracks local cost and outcome signals; it does not add those reports to agent context. CPAO — cost per accepted outcome — is the north-star metric, while Shadow Mode provides a baseline comparison for savings.

lean-ctx savings --period week                 # costs, token savings, and CPAO
lean-ctx value-report --format markdown --last 20  # recent outcome quality
lean-ctx shadow --latest                       # latest baseline comparison

Quick start: value tracking

# Enable shadow mode for savings comparison
echo '[shadow]\nenabled = true' >> ~/.config/lean-ctx/config.toml

# After using LeanCTX for a while:
lean-ctx savings
lean-ctx shadow --latest

<details> <summary><strong>Full feature list (complete MCP tool set)</strong></summary>

• Web & Research (ctx_url_read): pull a public web page, PDF, or YouTube transcript into context as compressed, citation-backed text — facts/quotes return claims with a confidence score + source URL, relevance-ranked research-compression distils to a token budget, SSRF-guarded (http/https only)
• Graph-Powered Intelligence: hybrid search (BM25 + embeddings + graph proximity via RRF), incremental git-diff updates
• LSP Refactoring (ctx_refactor): language-server-powered rename, references, go-to-definition via rust-analyzer, typescript-language-server, pylsp, gopls
• Multi-Agent (ctx_agent, ctx_handoff): agent handoff with context transfer bundles, diary system, synchronized shared state
• Archive Full-Text Search (ctx_expand search_all): FTS5-powered cross-archive search over all previously archived tool outputs
• PR Context Packs: lean-ctx pack --pr builds a PR-re