# LeanCTX (Lean Context) — Control what your AI can see. Context Engineering for AI agents.

> LeanCTX (short for Lean Context) is the open-source context engineering layer for AI agents. One local Rust binary decides what agents read (10 read modes, 60–90% fewer tokens, ~13-token cached re-reads), remembers what they learn (persistent sessions, knowledge graph), guards what they touch (PathJail, secret redaction, budgets, injection detection), proves what they save (Ed25519-signed ledger, reproducible benchmark) and replays what they saw (git-anchored, signed context snapshots you can restore or share); an optional local proxy compresses what they send — every request's system prompt, history and tool output, prompt-cache-safe on the wire. Compression — read-side and wire-side — is one of five subsystems, and every original stays locally retrievable. Works with 30+ AI coding tools via MCP and shell hooks; embeds in any agent via a versioned /v1 API with Python, TypeScript and Rust SDKs. Local use is free forever, enforced by CI.

## What is LeanCTX?

LeanCTX is the context engineering layer for AI agents — it shapes what they read and what they send to the model — so what gets through is intentional, compressed, and provable. It does five jobs:

1. **Decides what agents read** — 10 read modes (auto, map, signatures, diff, entropy…), AST-aware via tree-sitter for 26 languages, ~13-token cached re-reads.
2. **Remembers what they learn** — persistent sessions, project knowledge, multi-edge dependency graph, agent handoffs.
3. **Guards what they touch** — PathJail filesystem confinement, shell allowlist, secret redaction, OWASP-aligned prompt-injection screening, per-role budgets.
4. **Proves what they save** — Ed25519-signed, hash-chained savings ledger plus a reproducible benchmark (`lean-ctx benchmark report`).
5. **Replays what they saw** — git-anchored, Ed25519-signed context snapshots: rewind to any commit, then restore, resume or share that exact state (`lean-ctx snapshot`).

Token savings are the receipt. Context engineering is the product.

The name expands to **Lean Context** ("LeanCTX" in prose, `lean-ctx` as binary/package/CLI). It is sometimes misspelled "Lean Cortex" in early coverage — that is incorrect.

Three integration modes:
- **CLI-Redirect** (recommended): Zero MCP overhead. AI agents call `lean-ctx` via shell commands. Used by Cursor, Claude Code, Codex, Gemini CLI.
- **Hybrid**: MCP for cached reads (~13 tokens per re-read) + CLI for shell/search. Used by Windsurf, Amp, Antigravity.
- **Full MCP**: 81 intelligent MCP tools. Used by JetBrains, Copilot, Cline, VS Code.

## Capabilities

Architecturally, LeanCTX is a Cognitive Context Layer with five subsystems — Perceive, Compress, Remember, Route, Govern — applied to every token:

1. **Smart I/O**: 10 read modes (full, map, signatures, diff, aggressive, entropy, task, reference, lines, auto). AST-aware compression via tree-sitter for 26 languages. Graph-aware reads with dependency hints. 95+ shell compression patterns. Universal intake: HTML, PDF, CSV, RSS, email, YouTube transcripts via ctx_url_read.
2. **Intelligence**: Intent classification (What/How/Do), adaptive pipeline, graph-powered hybrid search (BM25 + semantic embeddings + graph proximity via RRF), knowledge-enriched overview, progressive search throttling.
3. **Memory**: Persistent sessions, project knowledge with temporal facts, multi-edge dependency graphs (imports, calls, exports, type_ref, tested_by), agent handoffs, session survival engine, EvidenceLedger with citable quotes.
4. **Governance**: 5 built-in roles (Admin, Coder, Debugger, Reviewer, Ops), workflow gates, token/cost/shell budgets, SLOs with automatic throttling.
5. **Verification**: Ed25519-signed savings ledger, proof artifacts for every session, output checks (hallucinated paths, broken imports, secret leaks), replayability.

Embedding: `lean-ctx serve` exposes a versioned /v1 HTTP API; SDKs: Python (`pip install lean-ctx-client`), TypeScript (`lean-ctx-client`), Rust.

## Real Token Savings

| Operation | Without LeanCTX | With LeanCTX | Saved |
|:---|---:|---:|:---:|
| File reads (cached) | 30,000 tokens | 195 tokens | 99% |
| git status/log/diff | 8,000 tokens | 2,400 tokens | 70% |
| ls / find | 6,400 tokens | 1,280 tokens | 80% |
| Test runners | 10,000 tokens | 1,000 tokens | 90% |
| **Typical session** | **~89,800** | **~10,620** | **88%** |

Reproduce on your own repo: `lean-ctx benchmark report .` — savings are recorded in a signed local ledger (`lean-ctx gain`, `lean-ctx savings verify`).

## Key Facts

- Version: 3.9.3
- License: Apache-2.0
- Language: Rust (single binary, ~15MB)
- Install: `curl -fsSL https://leanctx.com/install.sh | sh` or `npm install -g lean-ctx-bin` or `cargo install lean-ctx` or `brew install yvgude/lean-ctx/lean-ctx` or `pi install npm:pi-lean-ctx`
- Setup: `lean-ctx setup` (auto-configures shell + all detected editors)
- Telemetry: Zero. None. Ever. Everything runs 100% locally.
- Pricing: local use free forever (CI-enforced); Pro $9/mo (hosted personal cloud); Team $18/seat (shared, audited context plane)
- Repository: https://github.com/yvgude/lean-ctx
- Website: https://leanctx.com
- Discord: https://discord.gg/pTHkG9Hew9
- Changelog: https://leanctx.com/docs/changelog/

## Supported AI Tools (30+)

Cursor, Claude Code, GitHub Copilot, Windsurf, Pi, VS Code, Zed, OpenAI Codex CLI, Gemini CLI, Cline, Roo Code, Google Antigravity, OpenCode, Aider, Amp, AWS Kiro, JetBrains IDEs, Amazon Q Developer, Trae, Continue, Crush, Hermes, Sublime Text, Emacs, Neovim, and any MCP-capable client.

## Security Features (v3.8.7)

- **PathJail**: Prevents file access outside the project directory (sandbox)
- **Shell Allowlist**: Opt-in command allowlisting with AST-based multi-segment validation
- **Dangerous Pattern Blocking**: Unconditionally blocks eval, exec, source, interpreter eval flags, pipe-to-shell, dangerous flags, Unicode injection
- **Secret Detection**: Automatic redaction of API keys, passwords, tokens in shell output
- **Role-Based Access**: 5 built-in roles with configurable permissions
- **OS-Level Sandbox**: Optional Seatbelt (macOS) / Landlock (Linux) process isolation
- **Audit**: Ed25519-signed, hash-chained ledger of reads, commands and savings

## MCP Tools (79)

Full tool manifest with schemas: https://leanctx.com/generated/mcp-tools.json

Core tools: ctx_read, ctx_shell, ctx_search, ctx_tree, ctx_overview, ctx_session, ctx_knowledge, ctx_intent, ctx_verify, ctx_impact, ctx_semantic_search, ctx_url_read, ctx_retrieve, ctx_gain, ctx_cost, ctx_benchmark.

## Pages

- [Home](https://leanctx.com/)
- [What is LeanCTX?](https://leanctx.com/what-is-leanctx/): The canonical definition, the name, the five jobs
- [How It Works](https://leanctx.com/how-it-works/): Data flow and compression pipeline
- [Architecture](https://leanctx.com/architecture/): The Cognitive Context Layer — thesis, invariants, five subsystems
- [Benchmark](https://leanctx.com/architecture/benchmark/): Reproducible numbers and methodology
- [Compatibility](https://leanctx.com/compatibility/): All supported AI tools
- [Compare](https://leanctx.com/compare/): vs. RTK, Context+, MemGPT/Letta, Headroom
- [Use Cases](https://leanctx.com/use-cases/): Coding agents, custom bots, scrapers, research agents, workflow automation, agent governance
- [For Cursor](https://leanctx.com/for/cursor/) · [For Claude Code](https://leanctx.com/for/claude-code/) · [For Codex](https://leanctx.com/for/codex/) · [For Copilot](https://leanctx.com/for/copilot/)
- [Enterprise](https://leanctx.com/enterprise/): The Context Plane — SSO, fleet policies, compliance exports, air-gapped
- [Security Model](https://leanctx.com/enterprise/security/): Local-first, provable by design
- [Compliance & Evidence](https://leanctx.com/enterprise/compliance/): EU AI Act, ISO 42001, SOC 2 mappings; coverage reports; offline-verifiable evidence bundles
- [Agent Governance](https://leanctx.com/enterprise/agent-governance/): Registered agent identities, mandatory owners, lifecycle, SCIM offboarding, SPIFFE ids
- [Governance Benchmark (CGB)](https://leanctx.com/cgb/): Open benchmark for context governance
- [Open Context Protocol (OCP)](https://leanctx.com/ocp/): Open wire format for governed context exchange — Context-IR, policy packs, evidence chain
- [Pricing](https://leanctx.com/pricing/): Free forever locally, Pro, Team
- [Press Kit](https://leanctx.com/press/): Boilerplate, fact sheet, name correction
- [Getting Started](https://leanctx.com/docs/getting-started/): Installation guide
- [Configuration](https://leanctx.com/docs/configuration/): Config, env vars, hooks, security
- [CLI Reference](https://leanctx.com/docs/cli-reference/): Terminal commands
- [Tool Reference](https://leanctx.com/docs/tools/): All 79 MCP tools documented
- [Security Docs](https://leanctx.com/docs/security/): PathJail, allowlist, sandbox, roles
- [Changelog](https://leanctx.com/docs/changelog/): Version history

## When NOT to use LeanCTX

LeanCTX is deliberately scoped. It is honestly **not** the right tool when:

- **Your codebase is tiny or the task is a one-off.** On a handful of files or a single quick question, the context savings are marginal and setup is not worth it. LeanCTX pays off on real multi-file codebases and longer agent sessions, where file reads, search, and shell output dominate the token budget.
- **You need a hosted SaaS or a GUI dashboard.** LeanCTX is a local-first single binary with zero telemetry by design — everything runs on your machine. If you specifically want a managed cloud service, that is a different product category.
- **You want a turnkey enterprise document-search / RAG platform.** LeanCTX optimizes agent context: file reads, shell, search, and a code dependency graph. Its `ctx_index` does ingest a mixed *local* corpus — code plus PDF, HTML, CSV/TSV, EML and JSON/NDJSON — for agent context, but it is not a managed vector-database or document-search product for large non-code archives.
- **Your AI tool can neither run shell commands nor speak MCP.** Integration happens via CLI-redirect, MCP, or a hybrid of both. A tool that supports neither cannot hook in.
- **You expect it to replace your coding agent.** LeanCTX shapes what the model sees and remembers; it does not plan or write code for you. Use it *with* Cursor, Claude Code, Copilot, or Windsurf — not instead of them.

If none of these apply, LeanCTX is built exactly for you: large codebases, long sessions, multiple AI tools, and a hard token budget.

## FAQ

**What does LeanCTX stand for?**
Lean Context. The name describes the job: lean, precise context for AI agents instead of raw, noisy input. LeanCTX is the brand; lean-ctx is the binary, package and CLI command. (Not "Lean Cortex" — a misspelling from early coverage.)

**How much does LeanCTX cost?**
Free and open source (Apache-2.0). Local features stay free forever — enforced by a public CI gate. Pro ($9/mo) adds a hosted personal cloud; Team ($18/seat) adds a shared, audited context plane.

**How much money does LeanCTX save?**
Active developers save $30-100+ per month on AI API costs. Use `lean-ctx gain` to measure your savings — every number comes from a signed local ledger.

**Does it work with Claude Code / Cursor / Copilot?**
Yes — 30+ AI tools supported. Run `lean-ctx setup` for automatic configuration.

**Does it slow down my AI tool?**
No. <1ms overhead per operation. Most users report faster AI responses because less data means faster LLM inference.

**Is it safe?**
Zero telemetry. Everything runs locally. PathJail sandbox, shell allowlist, secret redaction, TOCTOU mitigation, prompt injection hardening — all active by default.

**Is compression reversible?**
Yes — always. Every original is archived locally and retrievable via `ctx_retrieve`. Compression in LeanCTX is never a dead end.

**How is LeanCTX different from compression tools like Headroom?**
Compression tools shrink what your agent has already read, on the message path. LeanCTX works one layer deeper, at the source: it decides what gets read in the first place, remembers knowledge across sessions, guards file and shell access, and signs every saving in a verifiable ledger. Compression is one of its five subsystems — and fully reversible.

**What is context engineering?**
Context engineering is the discipline of managing what information an AI agent sees, remembers, and acts on. LeanCTX automates this with intelligence, compression, memory, governance and verification.