Control what
your AI can see.
LeanCTX is the context engineering layer for AI agents — it shapes what they read (code, shell, docs, PDFs, the web) and what they send to the model (every request: system prompt, history and tool output, compressed on the wire). It decides what they read, remembers what they learn, guards what they touch, and signs the proof — so what crosses the model boundary is intentional, compressed, and provable.
60–90% fewer tokens. And that's just the receipt.
Open source · Local-first · Deterministic · Provable · Zero telemetry · One Rust binary · 30+ AI tools
A 2,000-token file. Re-read for 13.
curl -fsSL https://leanctx.com/install.sh | sh The agentic era has a context problem.
Every developer runs coding agents. Token spend is a top-3 engineering cost.
Fleets: 5–10 agents per developer (background, CI, review) talking to each other.
Agents in every department. Regulated, audited, budgeted.
More context makes models worse.
Context-rot research shows accuracy falling from 98% to 64% as noise fills the window. Trim the noise and accuracy climbs back. Cheaper is the side effect.
Every provider earns per token.
The layer that minimizes tokens can't come from the people who sell them. It has to sit on your side. This one does.
Now they want your memory.
Vendor agents now remember your company in a black box you can't move — a context login, not a model login. LeanCTX keeps the moat yours: portable, local memory you can swap any model under. Own your context; don't rent it back.
Three guarantees a vendor can't make.
When the window fills, native agents silently compact or drop what they read — you only notice when the answer quietly gets worse (Claude Code #42542). Cloud prose compressors send your context to a trained model and re-bill the rewrite. lean-ctx is the opposite layer: local, rule-based and explicit. That changes what it can promise.
Deterministic & model-agnostic.
Output is a pure function of content, mode and task — byte-identical on every run and CI-tested (#498). No vendor model update ever silently reclassifies your tokens, and nothing is dropped behind your back. Nothing is bound to one provider either: swap OpenAI, Anthropic or Gemini without losing context or cache.
Prompt-cache preserving.
History is pruned only at frozen, cache-aware boundaries, so Anthropic and OpenAI prompt caches keep hitting — you pay cheap cached-prefix rates instead of full-price rewrites.
100% local. Zero egress.
One Rust binary on your machine. Code and prompts never reach a third-party service — the only honest answer when your data-governance rule says nothing leaves the building.
And you don't trade away control or breadth: a single 0–1 aggressiveness dial and protected regions you mark as off-limits give the same zero-config feel as a cloud gateway — without the cloud. Shell-only compressors stop at the terminal; lean-ctx governs every read, search, memory and tool call, and signs the proof.
Reads less. Remembers more. Proves it.
Five things change the moment LeanCTX becomes your context engineering layer.
Compression makes context smaller. Context engineering makes it right. Five subsystems do the work; compression is one of them.
Watch it decide.
The same file. Three intents. Three different views: exploring gets a map, API work gets signatures, editing gets full code. You don't pick the mode — LeanCTX does.
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 Stop feeding your agents noise.
Code, shell output, search results, web pages, documents: whatever your agents take in, LeanCTX turns into compact, model-ready context. Each kind gets its own strategy.
Never a dead end. Every original stays locally retrievable, one ctx_retrieve away. LeanCTX tells your AI exactly when to ask for it.
Clean code, a lower AI bill
LeanCTX compresses how code reaches the model — the Code Health Engine attacks the other half of the bill: the intrinsic cost of the code itself. Complex, cryptically named, tightly coupled code makes an agent load more context, take more turns and re-read more often, and you pay for that confusion in tokens on every turn that touches it. It rolls up into a navigability score (0–100) and the estimated USD token tax of your hotspots.
Cognitive complexity
SonarSource's S3776, not cyclomatic count — it penalises deep nesting and tangled control flow an agent has to hold in its head, and rewards code that reads top to bottom.
Naming quality
Cryptic, single-letter or meaningless identifiers that force an agent to re-read the surrounding code just to infer what something is.
Module coupling
Afferent / efferent coupling and instability — how entangled a file is with the rest of the repo, which widens the blast radius (and the context) of any change.
Built for every agent. Including yours.
30+ AI tools
Cursor, Claude Code, Codex, Copilot, Windsurf, Cline and more. Auto-detected, zero config per tool.
Any language
Embed it in your own agent via lean-ctx serve: a versioned /v1 API with Python, TypeScript and Rust SDKs.
Any domain
Context personas reshape the layer for coding, research, support or data analysis. Or define your own.
Any data
Universal intake: code, HTML, PDF, CSV, email, RSS, even YouTube transcripts, compressed into facts and quotes.
IDE & Editor
CLI Agent
Platform
Bring the tools you already use.
An addon is any MCP tool wrapped in a tiny manifest. lean-ctx runs it behind one gateway and treats what it returns like your own code: compressed, searchable, in the same ctx_ tools. One command to add. Nothing to fork or recompile.
Compression
Drop in another compressor. What it returns folds into the same token budget as everything else.
Code intelligence
Packers, symbol maps and code-graphs land right inside ctx_expand and ctx_callgraph.
Memory
External memory stores feed the same ctx_knowledge your agent already reads.
Reasoning & plans
Planning and reasoning servers plug in next to the rest of your tools.
What are you building?
How teams put context engineering to work. Pick yours.
From solo builders to regulated fleets.
Builders
Solo developers and indie hackers who want their agent to read less, remember more, and stop burning tokens — on one local binary, free forever.
Local-free · 60–90% fewer tokens Explore BuildersTeams
Engineering teams that need a shared, audited context plane: consistent reads, pooled memory, and per-role budgets across every agent and IDE.
Shared memory · per-role budgets Explore TeamsEnterprise
Security and platform leaders who must prove what agents touched: SSO, fleet policies, signed evidence, and air-gapped, local-first by default.
SSO · policy packs · evidence bundles Explore EnterpriseControl, proof & security in one layer.
Govern what agents see. Prove what they save.
The controls and the receipts auditors actually ask for — built in, not bolted on.
Evidence Bundle v1
A signed, offline-verifiable record of what every agent read, ran and changed — checked with leanctx-verify.
Compliance coverage
Mapped reports for EU AI Act, ISO 42001 and SOC 2 controls.
Context policy packs
Declarative rules for what agents may read, run and remember — enforced before anything happens.
Agent registry & audit log
Every agent is a first-class identity; every decision lands in an org-wide trail.
Local by default. Provable by design.
Every read and every command passes through the context engineering layer before it touches your machine — or the model.
Local-first, zero telemetry
Everything runs on your machine. Nothing is sent anywhere by default.
PathJail
File access is confined to the paths you allow — nothing escapes the sandbox.
Shell allowlist
Dangerous commands are blocked before they ever run.
Secret & injection defense
Secrets and prompt-injection attempts are caught before they reach the model.
Same model. Fraction of the tokens.
Measured on real repo operations, reproducible end to end. Don't trust our numbers: run lean-ctx benchmark report . on your own repo.
Compression modes: tokens vs. information
Where the savings come from
Provable savings.
Every saving lands in an Ed25519-signed, hash-chained ledger on your machine. Export it for your CFO, or verify it against us.
How the ledger worksQuestions, answered.
LeanCTX (short for Lean Context) is the open-source context engineering layer for AI agents. One local Rust binary decides what agents read (10 read modes, 60–90% fewer tokens, ~13-token cached re-reads), remembers what they learn (persistent sessions, knowledge graph), guards what they touch (PathJail, secret redaction, budgets, injection detection), proves what they save (Ed25519-signed ledger, reproducible benchmark) and replays what they saw (git-anchored, signed context snapshots you can restore or share); an optional local proxy compresses what they send — every request's system prompt, history and tool output, prompt-cache-safe on the wire. Compression — read-side and wire-side — is one of five subsystems, and every original stays locally retrievable. Works with 30+ AI coding tools via MCP and shell hooks; embeds in any agent via a versioned /v1 API with Python, TypeScript and Rust SDKs. Local use is free forever, enforced by CI.
Read the full storyWhat is LeanCTX?
LeanCTX (short for Lean Context) is the open-source context engineering layer for AI agents. One local Rust binary decides what your agents read and compresses what they send, remembers what they learn, guards what they touch, and proves what they save in a signed ledger. It works with 30+ AI coding tools (Cursor, Claude Code, OpenAI Codex, GitHub Copilot and any MCP-capable client) and embeds in any agent via a versioned /v1 API.
Does compressing context hurt answer quality?
No. It usually improves it. Context-rot research shows model accuracy falling from 98% to 64% as windows fill with noise. LeanCTX removes redundancy while preserving meaning: AST-aware maps keep signatures and structure, shell patterns keep errors and results. Nothing is lost, either. Every original stays locally retrievable via ctx_retrieve.
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?
30+ and growing: Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Zed, Windsurf, Cline, Roo Code, Gemini CLI, OpenCode, JetBrains IDEs, and any MCP-capable client. Run lean-ctx setup once and every installed tool is auto-detected and configured.
What does LeanCTX stand for?
Lean Context. The name describes the job: lean, precise context for AI agents instead of raw, noisy input. LeanCTX is the brand and project name; lean-ctx is the binary, the package and the CLI command. (Not "Lean Cortex", a misspelling that appeared in early coverage.)
How is LeanCTX different from compression tools like Headroom?
Tools like Headroom compress the request on the wire — the proxy layer. LeanCTX already ships that layer: an optional local proxy (lean-ctx proxy enable) sits between your agent and the model and compresses every request — system prompt, history and tool results — before it's sent, prompt-cache-safe, metering the real dollars saved. So you usually don't need a separate request-compression proxy on top. And LeanCTX goes a layer deeper, at the source: it decides what gets read at all (10 read modes, ~13-token cached re-reads), remembers across sessions, guards file and shell access, and signs every saving in a verifiable ledger. Compression — read-side and wire-side — is one of its five subsystems, and it's fully reversible: every original stays one ctx_retrieve away.
Take back control of your context.
Start by saving tokens. Stay because everything your agents learn, touch and save is finally under your control. Free for local use, forever. A CI gate makes sure it stays that way.