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

Control what your AI can see. LeanCTX — short for Lean Context — is the context intelligence layer for AI agents: one local Rust binary that decides what your agents read, remembers what they learn, guards what they touch — and proves what they save.

Token savings are the receipt. Intelligence is the product. Works with Cursor, Claude Code, Copilot, Windsurf, Codex, Gemini and 30+ 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/.}

• Longer useful coding sessions — less context waste = more room for actual code reasoning
• Lower API costs — 60–90% fewer tokens on reads and shell output, cached re-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.

LeanCTX treats context as a managed resource, not an afterthought. One binary covers the four dimensions that decide how well an AI agent actually performs:

Your AI agent reads files and runs commands. LeanCTX compresses both automatically.

• File reads: 10 read modes (full, map, signatures, diff, lines:N-M, density:X, …) — cached re-reads cost ~13 tokens
• Target density (density:0.4): SDE-style budget compression — keeps the highest-entropy lines until ~40% of the original tokens remain, deterministic
• JIT disclosure: signatures carries line spans and points at lines:N-M for targeted expansion — outline first, bodies on demand
• Shell output: 95+ shell-output patterns compress git, npm, cargo, docker, kubectl, terraform and more (270 passthrough rules)
• Tree-sitter AST: structural understanding for 18 languages — not just text compression

Not every file needs the same depth. LeanCTX sends the signal, not the noise.

• 10 read modes: from full content down to AST signatures and entropy-filtered views
• Adaptive ModePredictor: learns the optimal read mode per file type from past sessions
• IntentEngine: classifies query complexity so simple lookups stay cheap

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

Performance is accuracy, not just speed. You stay in control of the window.

• 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): 4-layer verification engine with CI drift gates

LeanCTX is growing from a single context layer into a full cognitive context layer for whole teams: version-controlled context strategy, one unified graph, and a governance layer across many agents.

• Context as Code — declarative pipelines, profiles, and policies in TOML, versioned like infrastructure
• Unified Context Graph — code, tests, commits, CI runs, and knowledge entries in a single semantic graph
• Agent Harness — roles, budgets, and tool permissions for multi-agent governance
• Context Observability — SLOs on context consumption, anomaly detection, OpenTelemetry / Prometheus export

The full roadmap lives in VISION.md.

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

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

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 76 MCP tools are documented there).

lean-ctx onboard      # connect every detected AI tool
lean-ctx doctor       # confirm you're wired up

lean-ctx read src/server.rs -m map   # API surface, ~13 tok on re-read
lean-ctx -c "git status"             # compressed shell output

lean-ctx overview                    # task-aware project recap
lean-ctx knowledge recall "auth"     # facts that survive resets

lean-ctx graph impact src/auth.rs    # blast radius
lean-ctx smells scan                 # code-smell hotspots

lean-ctx provider list
lean-ctx serve --root ./api --root ./web   # multi-repo

lean-ctx doctor --fix
lean-ctx update

lean-ctx plan "refactor billing" --budget 8000
lean-ctx compile --mode balanced

ctx_agent action=register role=dev
ctx_handoff action=create        # baton-pass with full context

lean-ctx team serve --config team.toml
lean-ctx bootstrap            # zero-prompt CI setup

lean-ctx compression standard
lean-ctx harden               # enforce token discipline

lean-ctx gain --deep          # savings, cost, per-agent, heatmap
lean-ctx wrapped              # shareable recap (also: gain --svg / gain --share)
lean-ctx savings              # verified per-event ledger (auditable; savings verify)

LeanCTX is a standard MCP server, so it works with any MCP-compatible client. Two integration modes are auto-selected per agent:

Any MCP-compatible client works out of the box — the table above shows agents with first-class auto-setup.

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)

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

• Latest snapshot: BENCHMARKS.md
• Reproduce:

lean-ctx benchmark report .

• 2,600+ GitHub stars — and counting
• 260+ forks — active community contributions
• 200+ releases — shipped near-daily since launch
• 30+ supported AI coding agents — broadest MCP compatibility
• 76 MCP tools — from simple file reads to multi-agent orchestration
• Used in production by teams running Claude Code, Cursor, and Codex daily
• Live adoption metrics: leanctx.com/metrics — installs, stars and savings, updated continuously

• 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/
• What is LeanCTX: https://leanctx.com/what-is-leanctx/
• Comparison (vs RTK, Context+, MemGPT): https://leanctx.com/compare/
• Pricing & Cloud (local use is free forever): https://leanctx.com/pricing/
• FAQ: discord-faq.md
• Feature catalog (SSOT snapshot): LEANCTX_FEATURE_CATALOG.md
• Monorepo guide: docs/guides/monorepo.md
• Architecture: ARCHITECTURE.md
• Vision: VISION.md

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

One command removes everything — it stops all processes, then deletes hooks, editor configs, rules, autostart (LaunchAgent/systemd), the data dir, and the binary itself:

lean-ctx uninstall                 # full clean removal
lean-ctx uninstall --dry-run       # preview every change, write nothing
lean-ctx uninstall --keep-config   # keep MCP configs + rules (for reinstall)
lean-ctx-off                       # or just disable for the current shell session

No binary on PATH (or you used the curl installer)? Run the same removal from the installer:

curl -fsSL https://leanctx.com/install.sh | sh -s -- --uninstall

If you installed via a package manager, uninstall removes everything it wrote and tells you the one command to finish removing the binary:

brew uninstall lean-ctx        # Homebrew
cargo uninstall lean-ctx       # cargo install
npm uninstall -g lean-ctx-bin  # npm
pi uninstall npm:pi-lean-ctx   # Pi Coding Agent

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

Apache License 2.0 — see LICENSE.