LeanCTX is a context gateway for AI systems, positioned between AI tools and the information they read. It helps developers control what AI can "see" by selecting task-relevant context, applying access and content controls, and recording context operations and delivery evidence. The engine is open source, can run locally, supports CLI, MCP, hooks, and proxy paths, and also provides an SDK for embedding into applications.
Purpose and Positioning LeanCTX is primarily used in AI programming workflows, for example with Claude Code, Cursor, or Codex. It addresses issues such as repeated file reads, excessive shell output noise, wasted context windows, and loss of memory across sessions. Developers can retain model calls and application workflows themselves; LeanCTX is only responsible for the selection, control, and proof of context.
Main Capabilities Context compression: Supports 16 file read modes (such as full, map, signatures, diff, lines:N-M, density:X, etc.), and qualifying cached rereads return compact references instead of duplicate content. Supports target density compression (density:0.4), retaining high-entropy lines down to about 40% of the original tokens, using a deterministic algorithm. The JIT disclosure mechanism lets signatures carry line spans and expand on demand via lines:N-M. Shell output supports 85+ compression modes, covering git, npm, cargo, docker, kubectl, terraform, etc., and has 250+ passthrough rules. Provides structural understanding for 27 languages based on Tree-sitter AST. Source recovery (CCR) can expand compact views via ctx_expand, ctx_retrieve, or the reference API.
Intelligent triage: Adaptive ModePredictor learns the optimal read mode for each file type from historical sessions, and IntentEngine classifies query complexity, keeping simple queries low-cost.
Knowledge routing: Session memory (CCP) persists tasks, facts, and decisions across chats; the knowledge graph contains temporal facts with validity windows, episodic and procedural memory; Property Graph supports a multi-edge code graph (imports, calls, exports, type references) for impact analysis and search ranking. Memory remains local and portable, and can be exported as .ctxpkg package migration across machines or models. Usage and result evidence: Context Manager provides a browser dashboard to track tokens, compression statistics, and utilization in real time; supports budgets, SLOs, roles, and per-agent throttling policies; Context Proof (ctx_proof, ctx_verify) exports audit trails and checks policy claims at runtime. Shadow Mode simulates estimated savings based on uncompressed token counts, but does not measure answer quality. CPAO (cost per accepted outcome) serves as the core metric. Other capabilities: ctx_url_read can fetch web pages, PDFs, or YouTube transcripts into compressed, cited text, with SSRF protection; hybrid search combines BM25, embeddings, and graph proximity (RRF); LSP refactoring (ctx_refactor) supports rename, references, and go-to-definition; multi-agent research delivery (ctx_agent, ctx_handoff) is an experimental local feature; archive full-text search (ctx_expand search_all) is based on FTS5; PR context packs are built via lean-ctx pack --pr; context packs and snapshot time machine are research experimental features; observability commands such as lean-ctx gain --live, lean-ctx wrapped, lean-ctx watch, and the browser dashboard; verification savings are implemented through a local per-event ledger and a SHA-256 chain; HTTP mode provides Streamable HTTP MCP and /v1/tools/call via lean-ctx serve.
Usage After installation, supported integrations can be configured via lean-ctx setup. Common commands include lean-ctx wrap to register the MCP server and configure the local transport, and lean-ctx unwrap cursor to undo it. Claude Pro/Max subscription OAuth cannot use a custom ANTHROPIC_BASE_URL; wrap claude does not add a proxy redirect, and only enables ctx_* tools and shell output compression. On Windows, it can be built from source by running ./install.ps1. The current release workflow signs Windows binaries and the Python companion whe with Thinkery AG, and early versions may be unsigned. Disabling is available for the current shell via lean-ctx-off, no compression for a single command with lean-ctx -c --raw "git status", activation only for agent sessions can be set with shell_activation = "agents-only", and project-level configuration can be created with .lean-ctx.toml. Update with lean-ctx update, diagnose with lean-ctx doctor --json. When Docker projects share /workspace, .lean-ctx-id can be created to prevent context conflicts.
Applicable scenarios and limitations Suitable for daily coding, reducing repeated reads and noise, context continuity across sessions, multi-project environments, and AI workflows that require auditing and budget control. Limitations include: some features such as multi-agent, context packs, snapshot time machine, and Addons are still research experimental features; Shadow Mode reports simulated estimates and does not measure answer quality; secret scrubbing does not cover all possible secrets; Addons are untrusted by default and do not automatically install external servers; Claude wire-level request compression requires ANTHROPIC_API_KEY; hosted history or registry is not yet offered as a general product.l, early versions may be unsigned. Disabling is available for the current shell via lean-ctx-off, no compression for a single command with lean-ctx -c --raw "git status", activation only for agent sessions can be set with shell_activation = "agents-only", and project-level configuration can be created with .lean-ctx.toml. Update with lean-ctx update, diagnose with lean-ctx doctor --json. When Docker projects share /workspace, .lean-ctx-id can be created to prevent context conflicts.
Applicable scenarios and limitations Suitable for daily coding, reducing repeated reads and noise, context continuity across sessions, multi-project environments, and AI workflows that require auditing and budget control. Limitations include: some features such as multi-agent, context packs, snapshot time machine, and Addons are still research experimental features; Shadow Mode reports simulated estimates and does not measure answer quality; secret scrubbing does not cover all possible secrets; Addons are untrusted by default and do not automatically install external servers; Claude wire-level request compression requires ANTHROPIC_API_KEY; hosted history or registry is not yet offered as a general product.
