Your AI deserves
better context.
LeanCTX is one small Rust binary that perceives, compresses, remembers, routes, and governs every token between your AI and your codebase — automatically. Install it once: 60–90% fewer tokens per read, memory that survives across sessions, and guardrails on every tool call.
curl -fsSL https://leanctx.com/install.sh | sh Your AI is flying blind through your codebase.
It re-reads the same files every turn, forgets what it learned the moment a session ends, fills its context window with noise, and runs shell and file tools with no guardrails. The result: wasted tokens, slower answers, and decisions made on the wrong context.
"Compression saves tokens. But perceiving, remembering, routing and governing context — that's what changes the output."
Five things LeanCTX does to every token.
Between your AI and your code, one local binary runs the same five-step loop on every read, command, and search: perceive, compress, remember, route, and govern — so your AI sees the signal, keeps it, and stays in bounds.
Perceive
See what matters before you act.
Map an unfamiliar repo, surface the files and symbols that matter, and read structure instead of whole files — across 18 languages with tree-sitter.
ctx_overview → repo mapped in one call Compress
Every token carries signal.
Ten read modes, 95+ shell-output patterns and content-addressed caching shrink reads 60–90% and re-reads to ~13 tokens — the noise never reaches the model.
ctx_read → 4,200 → 920 tokens (78% saved) Remember
Continuity across sessions.
Findings, decisions and touched files persist and auto-restore into every new session, so your agent never re-explains context or re-reads what it already knows.
ctx_session → restored · 0 re-reads Route
The right context to the right model.
Detect intent, pick the read mode and token budget, and load only the tools a task needs — so each model sees exactly the context it should, and nothing more.
ctx_intent → right mode + budget per task Govern
Safe, measured, enforced.
PathJail, a shell allowlist, secret detection, role policies and token budgets keep every tool call in bounds — and analytics prove exactly what was saved.
ctx_verify → paths ok · secrets blocked Beyond the IDE: embed LeanCTX in your own agent via lean-ctx serve and the versioned /v1 API with Python, TypeScript and Rust SDKs, reshape it for any domain with Context Personas, index PDFs, HTML and CSV locally, and extend it with plugins and WASM — every local feature stays free.
Start where you are.
Twenty-eight code-grounded journeys, grouped into four tracks. Pick the one that sounds like you and follow it end to end — from your first install to running LeanCTX across a whole team.
Get Started
From zero to compressed reads in ten minutes — auto-detected for your editor.
Daily Workflow
Compressed reads, persistent memory and smart routing on every turn.
- J2 Daily Use Compressed reads, search and shell output on every turn — invisibly.
- J3 Memory & Knowledge Sessions, knowledge and checkpoints that auto-restore — never re-explain.
- J4 Code Intelligence Call graphs, impact analysis and repo maps across 18 languages.
- J7 Context Engineering & Observability Radar, control, compile and ledger for hands-on window management.
- J11 Analytics, Insights & Reporting Gain, token reports, dashboards and CEP to prove the payoff.
- J17 Beyond Coding: Web & Research Pull the web, PDFs and YouTube into context as compressed, cited evidence.
- J19 Context Firewall Runaway tool output becomes a compact digest plus a zero-loss retrieval ref.
Scale & Teams
Shared memory, providers and a team server — one brain across many agents.
- J5 Advanced & Integrations Proxy, external providers, plugins, packages and multi-repo wiring.
- J8 Multi-Agent Collaboration Shared memory, handoffs and diaries across many agents.
- J9 Team, Cloud & CI Team server, tokens, sync and headless CI runs.
- J15 Multi-Repo Workspaces Auto-detect, extra_roots and graph indexing across independent repos.
- J18 MCP Tool-Catalog Gateway Unlimited downstream MCP tools at a flat, constant context cost.
- J22 Build Your Own Agent: SDKs & /v1 API Embed LeanCTX in your own harness over a stable, discoverable /v1 contract.
- J23 Context Personas One switch reshapes the whole context surface for your domain.
- J24 Universal Intake: Docs, Data & Email Index any corpus — not just code — with format-aware extractors.
- J25 Extend Without Forking: Plugins & WASM Add tools, compressors and providers as sandboxed plugins or WASM — no fork.
Operate & Govern
Security, roles, budgets and performance tuning for real codebases.
- J6 Lifecycle & Maintenance Update, restart, clear caches and uninstall cleanly.
- J10 Customization & Governance Profiles, roles, rules and hardening to shape every tool call.
- J12 Troubleshooting Playbook Symptom → diagnosis → fix, with doctor and report-issue.
- J13 Security & Governance PathJail, shell allowlist, secret detection and role policies.
- J14 Performance Tuning Memory profiles, cache caps and limits for big repos.
- J16 Proof & Audit Sign your savings ledger into a tamper-evident receipt anyone can verify offline.
- J20 Per-item Sensitivity Floor Redact or drop sensitive items before anything reaches the model.
- J21 Reproducible Scorecard A self-verifying scorecard of compression, retrieval quality and latency.
- J26 Team Plane & the Local-Free Invariant Team RBAC, real plans and reproducible ROI — local stays free and ungated.
- J27 Self-Host the Team Server Run the audited team server on your own AWS or Docker infra — one shared brain for the org.
- J28 Prove Output Quality (With vs Without) A deterministic with/without A/B eval — pinned model, objective scorers, signed verdict.
Every kind of context, the right way.
LeanCTX applies a different strategy to each kind of context — so the model sees the signal, and you stay in control of the rest.
Nothing is lost. Compression is reversible — the full content is one
ctx_retrieve away, and LeanCTX tells your AI exactly when to ask for it.
You already have tools. Here's the difference.
LeanCTX isn't a replacement for grep or your editor — it's the layer that decides what's worth your AI's attention.
Why not just grep?
grep finds text. LeanCTX finds the right symbols, ranks them by relevance, and returns budgeted, structural context — not 500 raw matches you still have to read and filter.
Why not just read the files?
A raw read dumps 4,200 tokens when ~920 carry the signal. LeanCTX keeps the signal and drops the noise — and a cached re-read costs about 13 tokens instead of the whole file again.
Why not just compact more often?
Compaction throws away history you might still need. LeanCTX compresses losslessly: the full output is archived on disk and your agent retrieves it on demand — nothing is silently lost.
Why not another MCP server?
Most MCP servers add tool-definition overhead and hand back raw output. LeanCTX is a full cognitive context layer — caching, persistent memory, shell hooks, and a governance layer — in one local binary.
See compression in action.
Real TypeScript code. Real LeanCTX output. Pick a mode and watch the transformation.
import { verify, sign } from 'jsonwebtoken';
import { Redis } from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
const JWT_SECRET = process.env.JWT_SECRET!;
export async function authenticate(token: string) {
const payload = verify(token, JWT_SECRET);
const session = await redis.get(`session:${payload.sub}`);
if (!session) throw new Error('Session expired');
return JSON.parse(session);
}
export function refreshSession(userId: string) {
return sign({ sub: userId }, JWT_SECRET, { expiresIn: '1h' });
} exports: authenticate(token), refreshSession(userId)
deps: jsonwebtoken, ioredis
types: string → Promise<object>, string → string
lines: 17 size: 4,200 → 180 tokens
cached: 13 tokens on re-read Same model. Fraction of the tokens.
Compression modes — tokens vs. information
Where the savings come from
Works with every AI coding tool.
One install. Zero config per tool. LeanCTX auto-detects and integrates with all major AI coding tools.
IDE & Editor
CLI Agent
Platform
Questions, answered.
What is LeanCTX?
LeanCTX is an open-source context layer for AI coding agents. It sits between your AI tool — Cursor, Claude Code, OpenAI Codex, GitHub Copilot, and 24+ others — and the model, automatically compressing file reads, shell output, and search results so the agent spends far fewer tokens (up to 99% less on large operations) without losing the signal it needs.
Does compressing context hurt answer quality?
No. LeanCTX removes redundancy, not meaning: AST-aware file maps preserve signatures and structure, shell patterns keep the lines that matter (errors, results, diffs), and anything an agent later needs in full is re-expanded and netted out. The numbers in `lean-ctx gain` are the realized savings after those re-reads.
How do I install it?
One command, then one setup. Install via the script, Homebrew, npm, or cargo and run `lean-ctx setup` — LeanCTX auto-detects your editors and wires up the right hooks and MCP server for each. Upgrades are a single `lean-ctx update`.
Is any of my code or data sent to a server?
No. Compression, caching, the savings ledger, and project memory all run locally on your machine — nothing is uploaded. The only network features (the Wrapped share card and the public leaderboard) are strictly opt-in and publish just an anonymous, whitelisted aggregate: a token count and a display name you choose.
Which AI tools does it work with?
24+ and growing — Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Zed, Windsurf, Cline, Roo Code, Gemini CLI, OpenCode, and any MCP-capable client. LeanCTX integrates through native hooks where a tool supports them and through a standard MCP server everywhere else.
Stop guessing. Start seeing what's in your context.
One Rust binary. No cloud. No account. Apache-2.0 licensed. Install in 60 seconds — see what's in your context, then optimize it.