Lean Ctx

██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗ ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝ ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗ ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝

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)

# 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 (npm). Compress a chat-style messages array before it reaches any model — deterministic and prompt-cache friendly; images, tool-calls and ids pass through untouched.

# pip install lean-ctx-sdk
from lean_ctx import compress
messages = compress(messages, model="claude-sonnet-4")

// 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 (npm · crates.io). 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.

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

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?"

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."

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
• Source: yvgude/lean-ctx
• License: Apache-2.0
• Homepage: https://leanctx.com

Install and usage instructions live in the source repository linked above.