LeanCTX

LeanCTX is a context gateway for AI systems. It sits between AI tools and the files, repositories, tool results and configured providers they read. It selects task-relevant context, applies configured access and content controls, and records the context operations and delivery evidence it can observe. The open-source LeanCTX Engine runs locally through CLI, MCP, hooks and a proxy, and a separate LeanCTX SDK embeds supported Engine capabilities in applications.

What It Is

LeanCTX works on two paths. On the read path, an MCP server exposes ctx_* tools and shell hooks compress common command output. On the wire path, an opt-in local proxy routes supported model requests, so configured transformations can reduce eligible prompt, history and tool-result content. The host application keeps its own agent loop and model.

The README frames the workflow as Select, Control and Prove: choose the context a task needs, apply path permissions, content filters and budgets, then inspect source references, policy decisions and usage evidence.

How Context Is Selected and Compressed

• File reads offer 16 modes, including full, map, signatures, diff, line ranges and target-density views. Eligible cached re-reads return a compact reference.
• Shell-output patterns compress git, npm, cargo, docker, kubectl, terraform and similar commands.
• Tree-sitter AST analysis provides structural understanding for 27 languages.
• Compact views keep source or archive references that can be expanded again, depending on permissions, retention and source availability.
• Session memory and a knowledge graph persist tasks, facts and decisions across chats, and can be exported as .ctxpkg packages.

Measurement and Evidence

The CLI and a browser dashboard (the Context Manager) track token usage, compression stats and cost locally. lean-ctx savings keeps a per-event ledger. Shadow Mode estimates what the same work would have cost without LeanCTX using a simulated baseline; the README states it does not measure answer quality. The project also proposes Cost per Accepted Outcome (CPAO) as its comparison metric.

Setup Path

Install with a shell script, Homebrew, npm or cargo, then run lean-ctx wrap cursor (or claude, codex) to register the MCP server and supported transport for that agent. lean-ctx unwrap reverses it and lean-ctx doctor checks the setup. The agent compatibility matrix lists many agents and IDEs, split into hybrid (MCP plus shell hooks) and MCP-only modes.

Current Status

The latest listed release is v3.11.4. The README labels several areas as experimental research, including addons, multi-agent handoff, context time machine snapshots and team-server paths. Licensing is mixed: the repository lists Apache-2.0 for the core, while some modules may carry commercial source-visible terms.