Cognitive Context Layer

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.

- installs
- GitHub stars
1.8 MWh saved energy
lean-ctx session
$ lean-ctx read src/lib/auth.ts -m map
exports: authenticate(), validateToken(), refreshSession()
4,200 → 920 tokens (78% saved)
cached: 13 tokens on re-read
$ lean-ctx grep "authenticate" src/
3 matches in 0.8ms
auth.ts:14, middleware.ts:8, routes.ts:23
$ lean-ctx -c "cargo build --release"
Compiling LeanCTX in 3.2s
compressed: 847 → 42 tokens
curl -fsSL https://leanctx.com/install.sh | sh
60–90% fewer tokens per file read
10 read modes — one per intent
13 tokens per cached re-read
18 languages parsed via AST
01 The Problem

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

Without LeanCTX
AI reads 800-line file
→ Thousands of tokens sent to LLM
Includes comments, whitespace, imports
→ Slow, expensive, hits context limits
With LeanCTX
AI reads 800-line file
→ LeanCTX compresses via AST parsing
Keeps types, signatures, logic
→ 60–90% fewer tokens, same signal
02 How it Works

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.

01

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
02

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

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
04

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
05

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.

03 Find your journey

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.

PerceiveCompress
Start this track
04 What gets compressed

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.

What your AI does What LeanCTX does What reaches the model Typical savings
Source file read AST signatures + delta-loading Function & type skeleton — bodies on demand 75–90%
Cached re-read Returns the cached delta, not the file ~13 tokens — regardless of file size ~95%
Shell output 95+ pattern modules (git, cargo, npm, docker…) Status + the lines that matter 70–90%
Code search BM25 + dense ranking, deduplicated Top hits with exact locations 60–85%
Directory scan Depth-limited structural map The tree, without the clutter 50–80%

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.

05 Why not just…

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.

06 Live Demo

See compression in action.

Real TypeScript code. Real LeanCTX output. Pick a mode and watch the transformation.

src/lib/auth.ts
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' });
}
lean-ctx map mode
ctx_read output
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
07 Benchmark

Same model. Fraction of the tokens.

Compression modes — tokens vs. information

40%50%60%70%80%90%100% 0%20%40%60%80%100% Tokens consumed % Information preserved % BEST ↗ full 100% tok · 100% info map 25% tok · 85% info auto 18% tok · 82% info entropy 12% tok · 72% info signatures 7% tok · 55% info aggressive 4% tok · 40% info

Where the savings come from

Source file → map mode -75%
3,000 tok
750 tok
Source file → auto mode -82%
3,000 tok
540 tok
Shell: git diff -75%
2,000 tok
500 tok
Shell: cargo test -88%
2,500 tok
300 tok
Typical session: ~10,500 → ~2,090 tokens 80% saved
08 Compatibility

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

Cursor CLI-Redirect
VS Code MCP
Windsurf MCP
JetBrains MCP
Zed MCP
Sublime Text MCP
Emacs MCP
Neovim MCP
Continue MCP
Trae MCP

CLI Agent

Claude Code CLI-Redirect
GitHub Copilot MCP
Codex CLI CLI-Redirect
Gemini CLI CLI-Redirect
Cline MCP
Roo Code MCP
OpenCode MCP
Aider Shell Hook
Amp Shell Hook

Platform

Amazon Q MCP
AWS Kiro MCP
Antigravity MCP
Pi MCP
Qwen Code MCP
Verdent MCP
Hermes MCP
Crush MCP
09 FAQ

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.