# Lean Ctx > Control what your AI can see. LeanCTX (Lean Context) is the context intelligence layer for AI agents — one local Rust binary that decides what they read, remembers what they learn, guards what they touch, and proves what they save. 60–90% fewer tokens as the receipt. 76 MCP tools, 30+ agents, local-first. - **Type:** MCP server - **Install:** `agentstack add mcp-yvgude-lean-ctx` - **Verified:** Pending review - **Seller:** [yvgude](https://agentstack.voostack.com/s/yvgude) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [yvgude](https://github.com/yvgude) - **Source:** https://github.com/yvgude/lean-ctx - **Website:** https://leanctx.com ## Install ```sh agentstack add mcp-yvgude-lean-ctx ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About ██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗ ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝ ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗ ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ### **Control what your AI can see.** **LeanCTX — Lean Context Engineering for AI agents** LeanCTX — short for **Lean Context** — is the context engineering layer for AI agents. It runs as a single local binary between your agents and everything they touch — your code, shell, data, and the model itself: it **decides** what they read, **compresses** what they send (an optional local proxy shrinks every request — system prompt, history and tool results — prompt-cache-safe), **remembers** what they learn, **guards** what they touch — and **proves** what they save with a signed, verifiable savings ledger. The result: 60–90% fewer tokens — and that's the receipt, not the product. Zero config required. Local-first. | Problem | With LeanCTX | |---------|-------------| | Repeated file reads: ~2000 tokens each | Cached re-reads: **~13 tokens** | | Raw `git status`: ~800 tokens | Compressed: **~120 tokens** | | 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 | ---    Website  ·  Docs  ·  Install  ·  SDKs  ·  Scenarios  ·  Demo  ·  Benchmarks  ·  Cookbook  ·  Security  ·  Changelog --- > **Control what your AI can see.** LeanCTX — short for **Lean Context** — is the **context engineering layer** for AI agents: one local Rust binary that decides what your agents read, compresses what they send to the model, remembers what they learn, guards what they touch — and proves what they save. > 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. See it in action: Read + Shell Map-mode reads + compressed CLI output Gain (live) Tokens + USD savings in real time Benchmark proof Measure compression by language + mode All GIFs are generated from reproducible VHS tapes in demo/. ## Why developers use LeanCTX - **Longer useful coding sessions** — less context waste = more room for actual code reasoning - **Lower API costs** — 60–90% fewer tokens on reads and shell output, cached re-reads cost ~13 tokens - **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 --- Saves you tokens? Give it a star — it helps others discover LeanCTX. --- ## 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 — the four dimensions of context LeanCTX treats context as a managed resource, not an afterthought. One binary covers the four dimensions that decide how well an AI agent actually performs: ### 1. Compression — input efficiency Your AI agent reads files and runs commands. LeanCTX compresses both automatically. - **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 18 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 →](docs/comparisons/vs-headroom.md#reversibility) ### 2. Routing — the right fidelity per read Not every file needs the same depth. LeanCTX sends the signal, not 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. Memory — context that persists Context doesn't disappear between chats anymore. - **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. Verification — control what reaches the model Performance is accuracy, not just speed. You stay in control of the window. - **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 Full feature list (80 MCP tools) - **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-ready context pack (changed files, related tests, impact, artifacts) - **Context Packages**: `lean-ctx pack create` bundles Knowledge + Graph + Session into portable `.ctxpkg` files with SHA-256 integrity - **Context Time Machine**: `lean-ctx snapshot create|list|show|verify|restore|publish|import` — git-anchored, ed25519-signed snapshots of the layer state (lineage, ledger Φ, ROI, session) on an append-only timeline; replay them in the dashboard, `restore` to resume a session (and `--git` to check out the commit), or `publish`/`import` a signed snapshot to share it ([concept →](docs/concepts/context-time-machine.md)) - **Observability**: `lean-ctx gain --live` for real-time savings, `lean-ctx wrapped` for weekly/monthly summaries (`gain --svg`/`--share` for a shareable card or self-hostable page), `lean-ctx watch` for TUI monitoring - **Verified savings**: `lean-ctx savings` is an auditable, per-event ledger (tokenizer transparency, bounce-netting, tamper-evident SHA-256 chain) — local-only, on by default - **HTTP mode**: `lean-ctx serve` for Streamable HTTP MCP + `/v1/tools/call` (used by the Cookbook + SDK) ## Where it's going LeanCTX is growing from a single context *layer* into a full **cognitive context layer** for whole teams: version-controlled context strategy, one unified graph, and a governance layer across many agents. - **Context Time Machine → hosted history** — the snapshot engine, dashboard replay, restore, and signed file-based share/import have shipped (see above); next is a `ctxpkg.com` registry for hosted, versioned context history and a side-by-side model-view ｜ git-diff replay. The temporal axis through everything LeanCTX does — it *decides, remembers, guards, proves, and replays*. ([concept →](docs/concepts/context-time-machine.md)) - **Context as Code** — declarative pipelines, profiles, and policies in TOML, versioned like infrastructure - **Unified Context Graph** — code, tests, commits, CI runs, and knowledge entries in a single semantic graph - **Agent Harness** — roles, budgets, and tool permissions for multi-agent governance - **Context Observability** — SLOs on context consumption, anomaly detection, OpenTelemetry / Prometheus export The full roadmap lives in **[VISION.md](VISION.md)**. ## How it works (30 seconds) LeanCTX works on **two planes** — what your agents *read* and what they *send to the model*: ``` read path: AI tool → (MCP tools + shell) → lean-ctx → your repo + CLI wire path: AI tool → lean-ctx proxy → model provider (every request, compressed) ``` - **MCP server** *(read path)*: exposes `ctx_*` tools (read modes, caching, deltas, search, memory, multi-agent) - **Shell hook** *(read path)*: transparently compresses common commands so the LLM sees less noise - **Request proxy** *(wire path, opt-in)*: `lean-ctx proxy enable` puts a local proxy between your agent and the model that compresses **every request** — system prompt, full history and tool results — prompt-cache-safe, with measured USD spend. It can also pin **one reasoning-effort level across OpenAI, Anthropic & Gemini** (`proxy.effort`) without breaking that cache, cut **output** tokens with a cache-safe verbosity steer plus a measured holdout, and **relocate volatile fields** (dates, UUIDs, commit SHAs) out of the cacheable prefix so a stable system prompt finally caches. Every rewrite is reversible (content-addressed recovery) and byte-stable by contract. Same layer as a standalone request-compression proxy (e.g. Headroom) — you don't need one on top. - **Property Graph**: multi-edge code graph powers impact analysis, related file discovery, and search ranking - **Session memory**: persists state with structured recovery so long-running work never "cold starts" - **Context Manager**: browser dashboard for real-time visibility into what's in your context window ## Get started (60 seconds) ```bash # 1) Install (pick one) curl -fsSL https://leanctx.com/install.sh | sh # universal (no Rust needed) brew tap yvgude/lean-ctx && brew install lean-ctx # macOS / Linux npm install -g lean-ctx-bin # Node.js cargo install lean-ctx # Rust pi install npm:pi-lean-ctx # Pi Coding Agent # 2) Connect your AI tools (zero prompts, sensible defaults) lean-ctx onboard # or: lean-ctx setup (guided, full control) # 3) Verify lean-ctx doctor # 4) Restart your shell + AI tool, use it normally, then see the payoff lean-ctx gain # savings appear after your AI's first lean-ctx call ``` After onboarding, restart your shell and your editor/AI tool once so the MCP + hooks are active. `lean-ctx gain` is empty until your AI tool makes its first lean-ctx call — that's expected, not a misconfiguration. **Building from source on Windows?** Clone the repo and run `./install.ps1` in PowerShell — it builds the release binary and installs it into Cargo's bin directory (pass `-BuildOnly` to build without installing). Troubleshooting / Safety - Disable immediately (current shell): `lean-ctx-off` - Run a single command uncompressed: `lean-ctx -c --raw "git status"` - Only activate in AI agent sessions: set `shell_activation = "agents-only"` in `~/.config/lean-ctx/config.toml` - Per-project config override: create `.lean-ctx.toml` in your project root (auto-merged with global config) - Docker projects sharing `/workspace`: create `.lean-ctx-id` with a unique name to prevent context collisions - Update: `lean-ctx update` - Diagnose (shareable): `lean-ctx doctor --json` ## Use it from your own code (SDKs) Beyond the CLI, lean-ctx ships published libraries so you can call it directly from your app. **Drop-in prompt compression — [`lean-ctx-sdk`](https://pypi.org/project/lean-ctx-sdk/) ([npm](https://www.npmjs.com/package/lean-ctx-sdk)).** Compress a chat-style `messages` array before it reaches any model — deterministic and prompt-cache friendly; images, tool-calls and ids pass through untouched. ```python # pip install lean-ctx-sdk from lean_ctx import compress messages = compress(messages, model="claude-sonnet-4") ``` ```ts // npm install lean-ctx-sdk import { compress } from "lean-ctx-sdk"; messages = await compress(messages, { model: "gpt-4o" }); ``` Framework adapters included (LiteLLM, LangChain, Vercel AI SDK). → **[compress() cookbook](docs/guides/compress-sdk.md)** **Thin `/v1` contract clients — [`lean-ctx-client`](https://pypi.org/project/lean-ctx-client/) ([npm](https://www.npmjs.com/package/lean-ctx-client) · [crates.io](https://crates.io/crates/lean-ctx-client)).** Wrap the full `/v1` tool, event and session API over the process boundary — never links the engine, so it stays stable as lean-ctx evolves. ```bash pip install lean-ctx-client # Python (imports as `leanctx`) npm install lean-ctx-client # TypeScript / Node cargo add lean-ctx-client # Rust ``` Start the server with `lean-ctx serve`, then point a client at it. → **[API reference](https://leanctx.com/docs/api-reference/)** ## Real-world scenarios LeanCTX grows with you. Below are the journeys most people actually take — each links to a complete, function-by-function walkthrough in the **[Reference](docs/reference/README.md)** (every CLI command and all 79 MCP tools are documented there). ### 🟢 Your first 60 seconds *"I just installed it — now what?"* ```bash lean-ctx onboard # connect every detected AI tool lean-ctx doctor # confirm you're wired up ``` One command auto-detects Cursor/Claude/Codex/… and configures MCP + hooks. → **[Journey 1 — Setup & Onboarding](docs/reference/01-setup-and-onboarding.md)** ### 📖 Coding every day *"Stop re-reading the same files."* ```bash lean-ctx read src/server.rs -m map # API surface, ~13 tok on re-read lean-ctx -c "git status" # compressed shell output ``` Your agent reads less and searches smarter — automatically. → **[Journey 2 — Daily Use](docs/reference/02-daily-use.md)** … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [yvgude](https://github.com/yvgude) - **Source:** [yvgude/lean-ctx](https://github.com/yvgude/lean-ctx) - **License:** Apache-2.0 - **Homepage:** https://leanctx.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-yvgude-lean-ctx - Seller: https://agentstack.voostack.com/s/yvgude - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.