lean-ctx

██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗ ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝ ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗ ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝

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.

---

  

Website  ·  Docs  ·  Install  ·  Scenarios  ·  Demo  ·  Benchmarks  ·  Cookbook  ·  Security  ·  Changelog

---

Where it sits

Files · repositories · tool results · configured providers
                          │
                          ▼
                LeanCTX Context Gateway
                Select → Control → 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.
• 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.

Your work	Start here
Improve the context path of existing AI tools	Community setup
Apply shared context controls across an organization	Enterprise — licensed controls and deployment scope
Build context control into your application	LeanCTX SDK — stable interfaces and separate SDK/OEM terms

What is LeanCTX? · Where LeanCTX fits · Architecture

See it in action:

  <strong>Read + Shell</strong>
  
  Map-mode reads + compressed CLI output


  
  
  <strong>Gain (live)</strong>
  
  Token usage + estimated cost differences


  
  
  <strong>Benchmark proof</strong>
  
  Measure compression by language + mode

All GIFs are generated from reproducible VHS tapes in demo/.

Why developers use LeanCTX

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

---

Saves you tokens? Give it a star — it helps others discover LeanCTX.

---

Inside the LeanCTX Engine

Context Intelligence is how LeanCTX selects and prepares information for a task. These mechanisms support the Gateway's Select → Control → Prove flow.

1. Context Compression — input efficiency

For supported read and shell paths, LeanCTX can select compact representations of the files and command output your AI agent uses.

• Workload-specific token reduction on eligible context, with recovery paths and a local Shadow Mode baseline for measurement

• File reads: 16 read modes (full, map, signatures, diff, lines:N-M, density:X, …) — eligible cached re-reads return a compact reference instead of repeating content

• 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. Intelligent Triage — task understanding

Not every task or file needs the same depth. LeanCTX classifies the task, then sends the signal rather than the noise.

• 16 read modes: from full content down to AST signatures and entropy-filtered views
• Adaptive ModePredictor: learns the optimal read mode per file type from past sessions
• IntentEngine: classifies query complexity so simple lookups stay cheap

3. Knowledge Routing — cross-source context

Relevant code, sessions, and connected sources become focused context in