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

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 required. 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  ·  Scenarios  ·  Demo  ·  Benchmarks  ·  Cookbook  ·  Security  ·  Changelog

---

LeanCTX stands for Lean Context: 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 (67 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 .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)

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) Connect your AI tools (zero prompts, sensible defaults)
lean-ctx onboard          # or: lean-ctx setup  (guided, full control)

# 3) Verify
lean-ctx doctor

# 4) Restart your shell + AI tool, use it normally, then see the payoff
lean-ctx gain             # savings appear after your AI's first lean-ctx call

After onboarding, restart your shell and your editor/AI tool once so the MCP + hooks are active. lean-ctx gain is empty until your AI tool makes its first lean-ctx call — that's expected, not a misconfiguration.

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

Real-world scenarios

LeanCTX grows with you. Below are the journeys most people actually take — each links to a complete, function-by-function walkthrough in the Reference (every CLI command and all 67 MCP tools are documented there).

🟢 Your first 60 seconds "I just installed it — now what?" lean-ctx onboard # connect every detected AI tool lean-ctx doctor # confirm you're wired up One command auto-detects Cursor/Claude/Codex/… and configures MCP + hooks. → Journey 1 — Setup & Onboarding	📖 Coding every day "Stop re-reading the same files." lean-ctx read src/server.rs -m map # API surface, ~13 tok on re-read lean-ctx -c "git status" # compressed shell output Your agent reads less and searches smarter — automatically. → Journey 2 — Daily Use
🧠 Resume where you left off "My new chat forgot everything." lean-ctx overview # task-aware project recap lean-ctx knowledge recall "auth" # facts that survive resets Session memory + a project knowledge graph persist across chats. → Journey 3 — Memory & Knowledge	🗺️ Understand a new codebase "Where does this function ripple to?" lean-ctx graph impact src/auth.rs # blast radius lean-ctx smells scan # code-smell hotspots A multi-edge property graph powers impact analysis + ranked search. → Journey 4 — Code Intelligence
🔌 Wire in proxy, providers, plugins "Pull in GitHub issues and our Postgres schema." lean-ctx provider list lean-ctx serve --root ./api --root ./web # multi-repo External data flows through the same consolidation pipeline. → Journey 5 — Advanced & Integrations	🛠️ Keep it healthy "Update, fix, or cleanly remove." lean-ctx doctor --fix lean-ctx update Self-healing diagnostics; surgical uninstall that only removes its own blocks. → Journey 6 — Lifecycle & Troubleshooting
🎛️ Take control of the window "Budget my context like a pro." lean-ctx plan "refactor billing" --budget 8000 lean-ctx compile --mode balanced Phi-scored planning + knapsack compilation + a context ledger. → Journey 7 — Context Engineering	🤝 Run a team of agents "Planner + coder + reviewer on one repo." ctx_agent action=register role=dev ctx_handoff action=create # baton-pass with full context Shared message bus, diaries, knowledge, and deterministic handoffs. → Journey 8 — Multi-Agent Collaboration
🏢 Share across a team / CI "One shared index, headless in pipelines." lean-ctx team serve --config team.toml lean-ctx bootstrap # zero-prompt CI setup Scoped tokens, optional cloud sync, verifiable context gates. → Journey 9 — Team, Cloud & CI	🎚️ Tune & govern "Make it behave exactly how we want." lean-ctx compression standard lean-ctx harden # enforce token discipline Compression levels, tool profiles, themes, and rules governance. → Journey 10 — Customization & Governance
📊 Prove the payoff "Show me the numbers." lean-ctx gain --deep # savings, cost, per-agent, heatmap lean-ctx wrapped # shareable recap All analytics live in the CLI/dashboard — never burning agent tokens. → Journey 11 — Analytics & Insights	📚 The full reference "I want to read everything." Every command and all 67 MCP tools, organized as user journeys, plus appendices for the CLI map, MCP tools, and paths & config. → Reference index

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

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
• 67 MCP tools — from simple file reads to multi-agent orchestration
• Used in production by teams running Claude Code, Cursor, and Codex daily

Docs

• Reference (every function, by user journey): docs/reference/ — 11 journeys + CLI/MCP/config appendices
• 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
• Monorepo guide: docs/guides/monorepo.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.