Lean Context Engineering

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

159,135 installs
3,039 GitHub stars
2.0 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
savings ledger: signed ✓

A 2,000-token file. Re-read for 13.

curl -fsSL https://leanctx.com/install.sh | sh
60–90% fewer tokens per read
~13 tokens per cached re-read
30+ AI tools, auto-detected
26 languages parsed via AST
01 Why now

The agentic era has a context problem.

2026

Every developer runs coding agents. Token spend is a top-3 engineering cost.

2027

Fleets: 5–10 agents per developer (background, CI, review) talking to each other.

2028+

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.

02 What context engineering means

Reads less. Remembers more. Proves it.

Five things change the moment LeanCTX becomes your context engineering layer.

Without LeanCTX, your agent… With LeanCTX… The receipt
reads everything reads what matters 60–90% less per read
forgets everything remembers across sessions re-reads cost ~13 tokens
touches anything touches only what's allowed PathJail · redaction · budgets
proves nothing proves every saving Ed25519-signed ledger
can't revisit what it saw replays any past state git-anchored, signed snapshots

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.

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
How the savings add up

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.

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%
API response Schema-aware field extraction Useful fields, not payload soup 60–90%
Scraped page Boilerplate stripped, deduplicated Clean, model-ready content 70–95%
PDFs & docs Extracted into facts and quotes Citation-backed essentials 80–95%

Never a dead end. Every original stays locally retrievable, one ctx_retrieve away. LeanCTX tells your AI exactly when to ask for it.

Explore all ten read modes

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.

Explore the Code Health Engine
03 Universal

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

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
CodeBuddy MCP
OpenClaw MCP
Augment 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
Qoder MCP
QoderWork MCP

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.

HeadroomSophonRTK (Rust Token Killer)

Code intelligence

Packers, symbol maps and code-graphs land right inside ctx_expand and ctx_callgraph.

RepomixSerenaMCP Code Context

Memory

External memory stores feed the same ctx_knowledge your agent already reads.

Context-MemMem0Cognee

Reasoning & plans

Planning and reasoning servers plug in next to the rest of your tools.

Sequential ThinkingLean-MarkDown (lean-md)
04 Govern & secure

Control, 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.

05 Benchmark

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

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

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 works
06 FAQ

Questions, answered.

The one-paragraph definition

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 story
What 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.