lean-ctx

<div align="center"> <pre> ██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗ ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝ ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗ ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ </pre> **The Cognitive Context Layer for Agentic Systems** Your AI coding agent wastes thousands of tokens rereading files, parsing noisy shell output, and losing context between sessions. **LeanCTX fixes that.** One binary. Zero config. Local-first. | Problem | With LeanCTX | |---------|-------------| | Repeated file reads: ~2000 tokens each | Cached re-reads: **~13 tokens** | | Raw `git status`: ~800 tokens | Compressed: **~120 tokens** | | Context resets every chat | Session memory persists across chats | | No visibility into context usage | Real-time dashboard + budget control | --- <p> <a href="https://github.com/yvgude/lean-ctx/stargazers"><img src="https://img.shields.io/github/stars/yvgude/lean-ctx?style=social" alt="GitHub Stars"></a>&nbsp;&nbsp; <a href="https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml"><img src="https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml"><img src="https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml/badge.svg" alt="Security"></a> <a href="https://crates.io/crates/lean-ctx"><img src="https://img.shields.io/crates/v/lean-ctx?color=%23e6522c" alt="crates.io"></a> <a href="https://crates.io/crates/lean-ctx"><img src="https://img.shields.io/crates/d/lean-ctx?color=%23e6522c" alt="Downloads"></a> <a href="https://www.npmjs.com/package/lean-ctx-bin"><img src="https://img.shields.io/npm/v/lean-ctx-bin?label=npm&color=%23cb3837" alt="npm"></a> <a href="https://aur.archlinux.org/packages/lean-ctx"><img src="https://img.shields.io/aur/version/lean-ctx?color=%231793d1" alt="AUR"></a> <a href="https://pi.dev/packages/pi-lean-ctx"><img src="https://img.shields.io/badge/Pi.dev-pi--lean--ctx-6366f1?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHRleHQgeD0iNCIgeT0iMTgiIGZvbnQtc2l6ZT0iMTYiIGZvbnQtZmFtaWx5PSJzZXJpZiI+z4A8L3RleHQ+PC9zdmc+" alt="Pi.dev"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a> <a href="https://discord.gg/pTHkG9Hew9"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord"></a> <a href="https://x.com/leanctx"><img src="https://img.shields.io/badge/𝕏-Follow-000000?logo=x&logoColor=white" alt="X/Twitter"></a> <img src="https://img.shields.io/badge/Telemetry-Opt--in%20Only-brightgreen?logo=shield&logoColor=white" alt="Opt-in Telemetry"> </p> <p> <a href="https://leanctx.com">Website</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://leanctx.com/docs/getting-started">Docs</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#get-started-60-seconds">Install</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#demo">Demo</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#benchmarks">Benchmarks</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="cookbook/README.md">Cookbook</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="SECURITY.md">Security</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="CHANGELOG.md">Changelog</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://discord.gg/pTHkG9Hew9">Discord</a> </p> </div> --- > **LeanCTX** stands for **Lean Cortex**: a lightweight cognitive layer that helps AI agents perceive, compress, remember, route, and reuse context across workflows. > It governs every token between your code and the AI — so you make better decisions, not just cheaper ones. Works with **Cursor, Claude Code, Copilot, Windsurf, Codex, Gemini** and 23+ other agents — no config needed. <p align="center"><strong>See it in action:</strong></p> <table> <tr> <td align="center" width="33%"> <img src="assets/leanctx-demo.gif" width="320" alt="Map-mode file read + compressed git output demo"> <br/> <strong>Read + Shell</strong> <br/> Map-mode reads + compressed CLI output </td> <td align="center" width="33%"> <img src="assets/leanctx-gain.gif" width="320" alt="lean-ctx gain live dashboard demo"> <br/> <strong>Gain (live)</strong> <br/> Tokens + USD savings in real time </td> <td align="center" width="33%"> <img src="assets/leanctx-benchmark.gif" width="320" alt="lean-ctx benchmark report demo"> <br/> <strong>Benchmark proof</strong> <br/> Measure compression by language + mode </td> </tr> </table> <p align="center">_{All GIFs are generated from reproducible VHS tapes in <code>demo/</code>.}</p> ## Why developers use LeanCTX - **Longer useful coding sessions** — less context waste = more room for actual code reasoning - **Lower API costs** — 60-99% compression on shell output, cached 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 --- <p align="center"> <strong>Saves you tokens?</strong> <a href="https://github.com/yvgude/lean-ctx">Give it a star</a> — it helps others discover LeanCTX. </p> --- ## What it does **One binary. Three layers of value:** ### Layer 1: Compression (instant value) Your AI agent reads files and runs commands. LeanCTX compresses both automatically. - **File reads**: 10 modes (`full`, `map`, `signatures`, `diff`, `lines:N-M`) — cached re-reads cost ~13 tokens - **Shell output**: 56 pattern modules compress git, npm, cargo, docker, kubectl, terraform and more (270 passthrough rules) - **Tree-sitter AST**: structural understanding for 21 languages — not just text compression ### Layer 2: Memory (sticky value) 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 ### Layer 3: Governance & Observability (enterprise value) Know exactly where your context budget goes. Control it. - **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`): cryptographic proofs with 4-layer verification engine <details> <summary><strong>Full feature list (62 MCP tools)</strong></summary> - **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 - **Observability**: `lean-ctx gain --live` for real-time savings, `lean-ctx wrapped` for weekly/monthly summaries, `lean-ctx watch` for TUI monitoring - **HTTP mode**: `lean-ctx serve` for Streamable HTTP MCP + `/v1/tools/call` (used by the Cookbook + SDK) </details> ## How it works (30 seconds) ``` AI tool → (MCP tools + shell commands) → lean-ctx → your repo + CLI ``` - **MCP server**: exposes `ctx_*` tools (read modes, caching, deltas, search, memory, multi-agent) - **Shell hook**: transparently compresses common commands so the LLM sees less noise - **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) ```bash # 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) Setup (shell + auto-detected AI tools) lean-ctx setup # 3) Verify lean-ctx doctor # 4) See the payoff lean-ctx gain --live lean-ctx wrapped --week ``` After `setup`, restart your shell and your editor/AI tool once so the MCP + hooks are active. <details> <summary><strong>Troubleshooting / Safety</strong></summary> - 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` </details> ## Supported IDEs & AI tools lean-ctx is a standard **MCP server**, so it works with any MCP-compatible client. Two integration modes are auto-selected per agent: | Mode | How it works | Best for | |---|---|---| | **Hybrid** | MCP for cached reads (~13 tokens) + shell hooks for command compression | Agents with shell access (Cursor, Claude Code, Codex, ...) | | **MCP** | All 51+ tools via MCP protocol, no shell hooks | Protocol-only agents (JetBrains, VS Code, Zed, ...) | ### Agent compatibility matrix | Agent | Hybrid | MCP | Setup | |---|:---:|:---:|---| | Cursor | ● | | `lean-ctx init --agent cursor` | | Claude Code | ● | | `lean-ctx init --agent claude` | | Augment CLI / VS Code | ● | | `lean-ctx init --agent augment` | | Codex CLI | ● | | `lean-ctx init --agent codex` | | Gemini CLI | ● | | `lean-ctx init --agent gemini` | | Windsurf | ● | | `lean-ctx init --agent windsurf` | | GitHub Copilot | ● | | `lean-ctx init --agent copilot` | | CRUSH | ● | | `lean-ctx init --agent crush` | | Hermes | ● | | `lean-ctx init --agent hermes` | | OpenCode | ● | | `lean-ctx init --agent opencode` | | Pi | ● | | `lean-ctx init --agent pi` | | Qoder | ● | | `lean-ctx init --agent qoder` | | Amp | ● | | `lean-ctx init --agent amp` | | Cline | ● | | `lean-ctx init --agent cline` | | Roo Code | ● | | `lean-ctx init --agent roo` | | Kiro | ● | | `lean-ctx init --agent kiro` | | Antigravity | ● | | `lean-ctx init --agent antigravity` | | Amazon Q | ● | | `lean-ctx init --agent amazonq` | | Qwen | ● | | `lean-ctx init --agent qwen` | | Trae | ● | | `lean-ctx init --agent trae` | | Verdent | ● | | `lean-ctx init --agent verdent` | | Aider | | ● | `lean-ctx init --agent aider` | | Continue | | ● | `lean-ctx init --agent continue` | | JetBrains IDEs | | ● | `lean-ctx init --agent jetbrains` | | QoderWork | | ● | `lean-ctx init --agent qoderwork` | | VS Code | | ● | `lean-ctx init --agent vscode` | | Zed | | ● | `lean-ctx init --agent zed` | | Neovim | | ● | `lean-ctx init --agent neovim` | | Emacs | | ● | `lean-ctx init --agent emacs` | | Sublime Text | | ● | `lean-ctx init --agent sublime` | > **Any MCP-compatible client** works out of the box — the table above shows agents with first-class auto-setup. ### When to use (and when not to) **Great fit if you...** - use AI coding tools daily and your sessions are shell-heavy (git/tests/builds) - work in medium/large repos (50+ files / monorepos) - want a local-first layer with **no telemetry by default** **Skip it if you...** - mostly work in tiny repos and rarely call the shell from your AI tool - always need raw/unfiltered logs (you can still use `--raw`, but ROI is lower) <a id="demo"></a> ## Demo Try these in any repo: ```bash lean-ctx read rust/src/server/mod.rs -m map lean-ctx -c "git log -n 5 --oneline" lean-ctx gain --live lean-ctx dashboard # Context Manager (browser) lean-ctx watch # TUI monitor lean-ctx benchmark report . ``` - The repo ships the exact tapes used to render the GIFs in `demo/` - Regenerate locally: ```bash vhs demo/leanctx.tape vhs demo/gain.tape vhs demo/benchmark.tape ``` <a id="benchmarks"></a> ## Benchmarks - **Latest snapshot**: [BENCHMARKS.md](BENCHMARKS.md) - **Reproduce**: ```bash lean-ctx benchmark report . ``` ## By the numbers - **1,800+ GitHub stars** in 4 months - **190+ forks** — active community contributions - **181 releases** — shipped daily since launch - **28 supported AI coding agents** — broadest MCP compatibility - **62 MCP tools** — from simple file reads to multi-agent orchestration - Used in production by teams running Claude Code, Cursor, and Codex daily ## Docs - Getting started: https://leanctx.com/docs/getting-started - Tools reference: https://leanctx.com/docs/tools/ - CLI reference: https://leanctx.com/docs/cli-reference/ - Comparison (vs RTK, Context+, MemGPT): https://leanctx.com/compare/ - FAQ: [discord-faq.md](discord-faq.md) - Feature catalog (SSOT snapshot): [LEANCTX_FEATURE_CATALOG.md](LEANCTX_FEATURE_CATALOG.md) - Monorepo guide: [docs/guides/monorepo.md](docs/guides/monorepo.md) - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md) - Vision: [VISION.md](VISION.md) ## Privacy & security - **No telemetry by default** - **Optional anonymous stats sharing** (opt-in during setup) - **Disableable update check** (config `update_check_disabled = true` or `LEAN_CTX_NO_UPDATE_CHECK=1`) - **40+ security hardening fixes** in v3.5.16 (path traversal, injection, CSPRNG, CSP, resource limits — [details](CHANGELOG.md)) - Runs locally; your code never leaves your machine unless you explicitly enable cloud sync See [SECURITY.md](SECURITY.md). ## Uninstall ```bash lean-ctx-off # disable immediately (current shell session) lean-ctx uninstall # remove hooks + editor configs + data dir # Remove the binary (pick your install method) brew uninstall lean-ctx npm uninstall -g lean-ctx-bin cargo uninstall lean-ctx pi uninstall npm:pi-lean-ctx # Pi Coding Agent ``` ## Star History <a href="https://star-history.com/#yvgude/lean-ctx&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=yvgude/lean-ctx&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=yvgude/lean-ctx&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=yvgude/lean-ctx&type=Date" /> </picture> </a> ## Contributing Start with [CONTRIBUTING.md](CONTRIBUTING.md). Easy first PR: propose a new CLI compression pattern via the [issue template](.github/ISSUE_TEMPLATE/compression_pattern.md). ## License Apache License 2.0 — see [LICENSE](LICENSE). Portions of this software were originally released under the MIT License. See [LICENSE-MIT](LICENSE-MIT) and [NOTICE](NOTICE).