LeanCTX is the Context Gateway for AI Systems. Select task-relevant context, apply supported controls, connect local knowledge and inspect recorded evidence. Open-source Engine: CLI, MCP, hooks and supported proxy paths.
Tools
Tools
No tool list yet. Remote servers get one after the first health check.
LeanCTX is the Context Gateway for AI Systems. Select task-relevant context, apply supported controls, connect local knowledge and inspect recorded evidence. Open-source Engine: CLI, MCP, hooks and su
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
Does Lean Ctx need an API key?
No required environment variable is listed on this record.
What transport does Lean Ctx use?
Lean Ctx runs locally over stdio.
When was Lean Ctx last checked?
Last checked 2026-11-11. Focused input — use less of the context window for repeated reads and noisy output.. Configured controls — bound file access and filter supported results before delivery.. Continuity — retain local task, finding and decision records across sessions.
From the publisher
Documentation
LeanCTX
Context Gateway for AI Systems.
Control what your AI can see.
LeanCTX sits between AI tools and the information they read. It selects
task-relevant context, applies supported access and content controls before
delivery, and records the context operations and delivery evidence it can observe.
Your application, agent loop and model stay yours.
The open-source LeanCTX Engine runs locally through CLI, MCP, hooks and proxy paths.
The LeanCTX SDK embeds supported Engine capabilities in your application.
Where it sits
Files · repositories · tool results · configured providers
│
▼
LeanCTX Context Gateway
Select · Control · Learn · Prove
│
▼
Your AI application / agent
│
▼
Your model
Select: give AI the context the task needs, with search, structural views,
compression and reuse.
Control: apply configured path permissions, content filters and context
budgets to supported calls.
Key features
01. Focused input — use less of the context window for repeated reads and noisy output.
02. Configured controls — bound file access and filter supported results before delivery.
03. Continuity — retain local task, finding and decision records across sessions.
04. Existing tools — configure a supported integration with lean-ctx setup.
05. Inspectable usage — separate token estimates, provider observations and calculated costs.
06. Model choice — keep your own model calls and application workflow.
Learn: retain local task records and connect code and knowledge across
sessions, within the configured access and retention rules.
Prove: inspect source references, policy decisions and usage evidence.
A context-only integration records its prepared result; the host owns the
subsequent model call.
For coding workflows, start with Claude Code, Cursor or Codex.
The installation matrix distinguishes
first-class paths from other compatibility references.
Focused input — use less of the context window for repeated reads and noisy output.
Configured controls — bound file access and filter supported results before delivery.
Continuity — retain local task, finding and decision records across sessions.
Existing tools — configure a supported integration with lean-ctx setup.
Inspectable usage — separate token estimates, provider observations and calculated costs.
Model choice — keep your own model calls and application workflow.
Inside the LeanCTX Engine
The Engine puts Select, Control, Learn and Prove into the context paths of your
existing AI tools. Your host keeps control of the task, agent loop and model.
1. Select — the context each task needs
Search and structural views help an agent find relevant information before
reading entire files. Supported read and shell paths can return focused views
of files and command output, with references for recovering detail.
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: 85+ shell-output patterns compress git, npm, cargo, docker, kubectl, terraform and more (250+ passthrough rules)
Tree-sitter AST: structural understanding for 27 languages — not just text compression
Source recovery (CCR): supported compact views retain source or archive references for expansion through ctx_expand, ctx_retrieve or the reference API. Recovery depends on permissions, retention and the source remaining available. Read modes and detail →
2. Control — configured rules on supported paths
PathJail and roles: constrain tool filesystem access to the configured scope.
Content filters: configured detectors can warn, redact or block on supported
paths. Detection coverage and enforcement depend on the integration and settings.
Context budgets: bound selected input and supported tool output.
Host-owned model choice: the host chooses the model and performs any model
calls outside the Engine's observed path.
Review the security policy for defaults, supported controls and
coverage limits. A filesystem boundary is not an operating-system sandbox.
3. Learn — connect work across sessions
Keep useful task records and discover relationships between code and local
knowledge. Learning here means context continuity; it does not train your model.
Permission-bound reuse: access and retention rules still apply when stored
context is retrieved. Experimental .ctxpkg export is described under Research below.
4. Prove — inspect what the Engine recorded
Inspect source references, recorded policy decisions and delivery evidence from
supported paths. lean-ctx inspect explains observed context operations. A
context-only integration records its prepared result; it cannot prove a later
model call made by the host.
Audit export: retain the recorded evidence for review within its stated scope.
Context Proof (ctx_proof, ctx_verify): exportable audit trail (verifier, SLO, pipeline and provenance records) plus runtime-checked policy claims (PathJail per touched file, budget)
Usage and cost — measure the result
Context controls and evidence come first. Usage estimates and calculated costs
help you assess their operational effect; they do not prove answer quality.
Shadow Mode — a simulated baseline
Shadow Mode estimates what the same work would have cost without LeanCTX,
without changing the active workflow. The baseline is simulated from the
uncompressed token counts and the same outcome signals, not a second measured
run, so its reports estimate cost, tokens and CPAO deltas; they do not measure
answer quality.
LeanCTX records local cost and outcome signals without adding those reports to
agent context. CPAO (cost per accepted outcome) is one comparison metric; Shadow
Mode provides simulated savings estimates. Keep estimates, provider-measured
usage and outcome quality separate.
# Enable shadow mode for savings comparison
lean-ctx config set shadow.enabled true
# After using LeanCTX for a while:
lean-ctx savings
lean-ctx shadow --latest
Web & Research (ctx_url_read): pull a public web page, PDF, or YouTube transcript into context as compressed, citation-backed text — facts/quotes return claims with a confidence score + source URL, relevance-ranked research-compression distils to a token budget, SSRF-guarded (http/https only)
Multi-Agent — Research (ctx_agent, ctx_handoff): experimental local agent handoff with context transfer bundles, diary system, and shared state; not a hosted or generally available team service
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 — Research: lean-ctx pack create bundles local Knowledge, Graph and Session state into .ctxpkg files with SHA-256 integrity; this is experimental local packaging, not a generally available Context Kits or hosted sharing product
Context Time Machine — Research: lean-ctx snapshot create|list|show|verify|restore|publish|import handles git-anchored, signed local snapshots and file-based sharing; dashboard replay and restore are experimental, and hosted history or a hosted registry is not a generally available product (concept →)
Observability: lean-ctx gain --live, lean-ctx wrapped, lean-ctx watch and the browser dashboard show local activity and recorded context metrics; gain --svg/--share creates a shareable card or self-hostable page
Usage ledger: lean-ctx savings is a local per-event ledger with tokenizer transparency, bounce-netting and a tamper-evident SHA-256 chain; provider-measured savings require the proxy's counterfactual holdout
HTTP mode: lean-ctx serve for Streamable HTTP MCP + /v1/tools/call (used by the Cookbook and external clients)
Addons — Research preview
Addon manifests and gateway integration remain experimental Research interfaces.
Local addon release|add|list commands handle signed packages; they do not
provide a public marketplace, hosted registry, managed distribution or addon search. A package can carry a sandboxed WASM module or an [mcp] declaration
for an external server.
lean-ctx addon release ./my-addon # build a signed .ctxpkg — no artifact host, no CI
lean-ctx addon add ./my-addon-1.0.0.ctxpkg # verify, disclose, ask, install
lean-ctx addon list # what's installed, what loads, what's wired
Publish it yourself — the module travels inside the signed package, so
the signature covers the executable bytes. Nothing external to host, hash or
serve, and no pipeline of your own.
Verified locally, then asked — add re-checks the signature on your
machine rather than trusting its source, checks every module against its
pinned SHA-256, prints the publisher key and the exact command any declared
server would run, and only then prompts.
LeanCTX never installs the server for you — no uv tool install, no
npx. Fetching a declared tool stays your step, where your own package
manager's trust model applies. The manifest says how to run it.
Folded in, not just proxied — opt-in post-processing runs addon output through the same pipeline as your code: compress to a budget, spill oversized blobs to a ctx_expand handle, index into BM25 / graph / knowledge. A typed integration routes specific tools straight into ctx_expand, ctx_callgraph and ctx_knowledge.
Untrusted by default — addon results pass through secret scrubbing and are tagged untrusted in the integration pipeline. Scrubbing covers configured detection patterns, not every possible secret.
The local workflow verifies signatures and module hashes, shows the publisher
key and declared command before installation, and never installs the external
server. Opt-in post-processing can send addon results through compression,
ctx_expand, BM25, graph and knowledge. Results remain untrusted; configured
secret scrubbing does not cover every possible secret. See the
status-qualified addon guide for the boundary.
Research directions
LeanCTX remains the Context Gateway for AI Systems. These research directions
extend its context capabilities; they are not supported product commitments.
Hosted context history — local snapshot create/show/verify/restore and signed file-based sharing are experimental Research; a hosted registry and model-view comparison remain future work. (concept →)
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
Cross-agent context controls — explore context roles, budgets, and permissions while the host retains agent scheduling and workflow execution
Shell hook(read path): transparently compresses common commands so the LLM sees less noise
Request proxy(wire path, opt-in): lean-ctx proxy enable routes supported requests through a local proxy. Configured transformations can reduce eligible prompt, history and tool-result content while respecting supported provider-cache boundaries. Provider-specific effort mapping (proxy.effort), verbosity controls and volatile-prefix handling have their own compatibility limits. Recovery requires retained, authorized artifacts; usage and cost evidence depend on the provider data the path observes.
Property Graph: multi-edge code graph powers impact analysis, related file discovery, and search ranking
Session memory: persists selected session state for recovery when authorized records remain available
Context Manager: browser dashboard for inspecting context activity and records visible to LeanCTX
Get started
# 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
# 2) One-command setup for your agent
lean-ctx wrap cursor # or: wrap claude / wrap codex
# Inspect recorded context metrics after your AI's first lean-ctx call.
lean-ctx gain
lean-ctx wrap registers the MCP server and configures the supported local
transport for that agent. Undo anytime with lean-ctx unwrap cursor.
Claude Pro/Max: subscription OAuth cannot use a custom
ANTHROPIC_BASE_URL. lean-ctx wrap claude therefore adds no proxy redirect
while enabling the ctx_* tools and shell-output compression; an existing
custom endpoint remains untouched.
Claude wire-level request compression requires ANTHROPIC_API_KEY. See
advanced proxy setup.
lean-ctx onboard # connect all detected AI tools (zero prompts)
lean-ctx setup # interactive wizard with every option
Building from source on Windows? Clone the repo and run ./install.ps1 in PowerShell — it builds the release binary and installs it into Cargo's bin directory (pass -BuildOnly to build without installing).
The current release workflow signs new Windows binaries as Thinkery AG,
including the binaries inside ZIP archives and Python companion wheels.
Earlier releases may still contain unsigned executables. Signing does not
guarantee acceptance by every Windows security policy.
If Windows blocks an older unsigned download, use WSL or build locally with
cargo install lean-ctx; do not disable system-wide security protections for
this tool. Windows-side MCP clients can launch the WSL installation with
wsl lean-ctx mcp.
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 the complete MCP
tools are documented there).
🟢 Your first setup
"I just installed it — now what?"
lean-ctx wrap cursor # one-command setup for your agent
lean-ctx doctor # confirm you're wired up
lean-ctx team serve --config team.toml
lean-ctx bootstrap # zero-prompt CI setup
Experimental local team-server path with scoped tokens and verifiable context
gates; no hosted team or cloud service is publicly available.
→ Journey 9 — Team, Cloud & CI
🎚️ Tune & govern
"Make it behave exactly how we want."
lean-ctx compression standard
lean-ctx harden # enforce token discipline
LeanCTX provides an MCP server. Client support depends on transport, tool
handling, and configuration; the matrix below records the integration scope.
Two integration modes are selected for supported agents:
Mode
How it works
Best for
Hybrid
MCP for cached reads and references + shell hooks for command compression
Agents with shell access (Cursor, Claude Code, Codex, ...)
MCP
Complete tool set 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
CodeBuddy
●
lean-ctx init --agent codebuddy
Augment CLI / VS Code
●
lean-ctx init --agent augment
Codex CLI
●
lean-ctx init --agent codex
Grok
●
lean-ctx init --agent grok
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
Mistral Vibe
●
lean-ctx init --agent vibe
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
MCP clients need compatible transport, tool support, and configuration. The table lists setup targets; the client constraints distinguish verified integrations from generic compatibility.
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 local context processing with inspectable network and telemetry controls
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)
The honest fine print: the payoff depends on three levers — reach (own the
window via the proxy/engine, not just the ctx_* tool layer), context
lifetime (one long-lived session vs. a fresh process per phase), and
provider pricing (prompt-cache-priced vs. re-billed every turn). They stack
into a clear win where they line up and net to break-even where they don't.
See the win vs. break-even matrix
for the full breakdown and how to tune for each case.
Measurements and estimates require a declared workload and method. The earlier per-read-mode
compression table (map / signatures over 50 files) is withdrawn along
with the other historical figures in BENCHMARKS.md; measure
your own repository with lean-ctx benchmark report . instead. Cache references
can reduce repeated context; their token cost depends on the emitted result and tokenizer.
Measure the Engine's own advertised schema, instruction, and briefing overhead
with lean-ctx doctor overhead --gate. The deterministic
lean-ctx benchmark dual-arm --json replay reports a synthetic upper bound:
its baseline never uses the provider's prompt cache, while agent hosts can cache
the prefix with or without LeanCTX. It is not a provider invoice, an on/off
comparison or an outcome-quality evaluation. Available comparison methods include
the lean-ctx eval ab subcommand (requires a suite file via --suite), the
injected-context footprint comparison in lean-ctx eval footprint (requires a
suite via --suite and a baseline via --compare), and the proxy's opt-in compression holdout
([proxy] compression_holdout).
Accuracy is gated, within stated limits. A model-free A/B gate checks that the JSON
crusher keeps every gold answer in its fixtures while cutting tokens, and proxy
rewrites preserve stable output for prompt-cache eligibility under the same inputs and settings.
Actual cache hits, prices, and discounts depend on the provider. The off-vs-on testbench (lean-ctx eval testbench)
runs pinned real repos through a raw-dump baseline and through lean-ctx at an
identical token budget, grades free-form QA with an LLM judge and code with each
repo's own tests, and emits FINDINGS.md (tokens / turns / walltime / quality) plus a
regressions file. What CI replays is a small committed recording: it is a
mechanism gate (it catches a broken pipeline or a changed grade), not evidence
that compression preserves answer quality. Every eval report states its evidence
tier (A mechanism … E production); a run below 30 paired tasks is
UNDERPOWERED and fails --gate unless run as an explicit --mechanism check — see
context-quality-v1.
A powered with/without quality study has not been run yet; the proxy's
compression holdout measures prompt size on real traffic and reports answer
quality as unknown. What each number can and cannot show, per data path:
measurement scope.
Inspectable telemetry controls: run lean-ctx telemetry status to see the effective setting and lean-ctx telemetry show to inspect the payload; lean-ctx telemetry disable turns reporting off.
Disableable update check (config update_check_disabled = true or LEAN_CTX_NO_UPDATE_CHECK=1)
Context processing runs locally; configured source providers, proxy/model requests, submitted feedback, updates, and enabled telemetry have their own network paths.
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:
Mixed licensing: the Trust Core remains Apache-2.0 while explicitly mapped v4
modules may use commercial source-visible terms. See LICENSE.md
and LICENSE_MATRIX.toml.
