██╗     ███████╗ █████╗ ███╗   ██╗     ██████╗████████╗██╗  ██╗
██║     ██╔════╝██╔══██╗████╗  ██║    ██╔════╝╚══██╔══╝╚██╗██╔╝
██║     █████╗  ███████║██╔██╗ ██║    ██║        ██║    ╚███╔╝ 
██║     ██╔══╝  ██╔══██║██║╚██╗██║    ██║        ██║    ██╔██╗ 
███████╗███████╗██║  ██║██║ ╚████║    ╚██████╗   ██║   ██╔╝ ██╗
╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝     ╚═════╝   ╚═╝   ╚═╝  ╚═╝

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

---

  

Website  ·  Docs  ·  Install  ·  Demo  ·  Benchmarks  ·  Cookbook  ·  Security  ·  Changelog  ·  Discord

---

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.

See it in action:

Read + Shell Map-mode reads + compressed CLI output

Gain (live) Tokens + USD savings in real time

Benchmark proof Measure compression by language + mode

_{All GIFs are generated from reproducible VHS tapes in demo/.}

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

---

Saves you tokens? Give it a star — it helps others discover LeanCTX.

---

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

Full feature list (51+ MCP tools)

• 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 .lctxpkg 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)

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)

# 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.

Troubleshooting / Safety

• 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

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
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)

Demo

Try these in any repo:

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:

vhs demo/leanctx.tape
vhs demo/gain.tape
vhs demo/benchmark.tape

Benchmarks

• Latest snapshot: BENCHMARKS.md
• Reproduce:

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
• 51+ 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
• Feature catalog (SSOT snapshot): LEANCTX_FEATURE_CATALOG.md
• Architecture: ARCHITECTURE.md
• Vision: 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)
• Runs locally; your code never leaves your machine unless you explicitly enable cloud sync

See SECURITY.md.

Uninstall

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

Contributing

Start with CONTRIBUTING.md. Easy first PR: propose a new CLI compression pattern via the issue template.

License

Apache License 2.0 — see LICENSE.

Portions of this software were originally released under the MIT License. See LICENSE-MIT and NOTICE.