lean-ctx

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
• CCP: persists session state with structured recovery queries so long-running work doesn’t “cold start” every chat

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.

• Disable immediately (current shell): lean-ctx-off
• Run a single command uncompressed: lean-ctx -c --raw "git status"
• 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. Three integration modes are auto-selected per agent:

| Mode | How it works | Best for | |---|---|---| | CLI-Redirect | Agent calls lean-ctx directly via shell — zero MCP schema overhead | Agents with shell access | | Hybrid | MCP for cached reads (13 tokens), CLI for shell + search | Mixed environments | | Full MCP | All 57 tools via MCP protocol | Protocol-only agents |

Agent compatibility matrix

| Agent | CLI | Hybrid | MCP | Setup | |---|:---:|:---:|:---:|---| | Cursor | ● | | | lean-ctx init --agent cursor | | Codex CLI | ● | | | lean-ctx init --agent codex | | Gemini CLI | ● | | | lean-ctx init --agent gemini | | Claude Code | | ● | | lean-ctx init --agent claude | | 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 | | Windsurf | | ● | | lean-ctx init --agent windsurf | | GitHub Copilot | | ● | | lean-ctx init --agent copilot | | 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 | | 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 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 .

Docs

• Getting started: https://leanctx.com/docs/getting-started
• Tools reference: https://leanctx.com/docs/tools/
• CLI reference: https://leanctx.com/docs/cli-referenc