# LeanCTX

> Open-source context gateway that selects, controls, and records the context AI coding tools and agents read.

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.

## Features
- Context gateway: select, control and prove flow
- 16 file read modes including map, signatures, diff and density
- Shell output compression for 85+ command patterns
- Tree-sitter AST structural analysis for 27 languages
- Source recovery via ctx_expand and ctx_retrieve
- Session memory and knowledge graph persisting across chats
- Property graph for impact analysis and search ranking
- Opt-in local request proxy for model requests
- Path permissions, content filters and context budgets
- Local cost, savings ledger and Shadow Mode estimates
- Browser dashboard (Context Manager)
- Signed local addon packages (research preview)
- Web, PDF and YouTube transcript reading into context
- Configurable telemetry and update checks

## Integrations
Cursor, Claude Code, Codex CLI, Gemini CLI, Windsurf, GitHub Copilot, Cline, Roo Code, Aider, Continue, JetBrains IDEs, VS Code, Zed, Neovim, Emacs, Sublime Text, Kiro, Amazon Q, OpenCode, Amp

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, VSC_EXTENSION, JETBRAINS_PLUGIN, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v3.11.4

## Links
- Website: https://leanctx.com
- Documentation: https://leanctx.com/docs/getting-started
- Repository: https://github.com/yvgude/lean-ctx
- EveryDev.ai: https://www.everydev.ai/tools/lean-ctx