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 · Learn · 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.
• Learn: retain local task records and connect code and knowledge across sessions, within the configured access and retention rules.
• 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

Read + Shell

Map-mode reads + compressed CLI output

Gain (terminal)

Token usage + estimated cost differences

Benchmark measurement

Measure compression by language + mode

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.

---

Find LeanCTX useful? Give it a star — it helps others find the Context Gateway for AI systems.

---

Inside the LeanCTX Engine

The Engine puts Select, Control, Learn and Prove into the context paths of your existing AI tools. Your host keeps control of the task, agent loop and model.

1. Select — the context each task needs

Search and structural views help an agent find relevant information before reading entire files. Supported read and shell paths can return focused views of files and command output, with references for recovering detail.

• 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 or the reference API. Recovery depends on permissions, retention and the source remaining available. Read modes and detail →

2. Control — configured rules on supported paths

• PathJail and roles: constrain tool filesystem access to the configured scope.
• Content filters: configured detectors can warn, redact or block on supported paths. Detection coverage and enforcement depend on the integration and settings.
• Context budgets: bound selected input and supported tool output.
• Host-owned model choice: the host chooses the model and performs any model calls outside the Engine's observed path.

Review the security policy for defaults, supported controls and coverage limits. A filesystem boundary is not an operating-system sandbox.

3. Learn — connect work across sessions

Keep useful task records and discover relationships between code and local knowledge. Learning here means context continuity; it does not train your model.

• Session memory (CCP): persist task/facts/decisions across chats — structured recovery queries survive compaction
• Knowledge graph: temporal facts with validity windows, relations and lifecycle
• Property Graph: multi-edge code graph (imports, calls, exports, type_ref) powers impact analysis and search ranking
• Permission-bound reuse: access and retention rules still apply when stored context is retrieved. Experimental .ctxpkg export is described under Research below.

4. Prove — inspect what the Engine recorded

Inspect source references, recorded policy decisions and delivery evidence from supported paths. lean-ctx inspect explains observed context operations. A context-only integration records its prepared result; it cannot prove a later model call made by the host.

• Cockpit (lean-ctx cockpit): local browser view with token tracking, compression stats, spend and recorded calls
• Audit export: retain the recorded evidence for review within its stated scope.
• Context Proof (ctx_proof, ctx_verify): exportable audit trail (verifier, SLO, pipeline and provenance records) plus runtime-checked policy claims (PathJail per touched file, budget)

Usage and cost — measure the result

Context controls and evidence come first. Usage estimates and calculated costs help you assess their operational effect; they do not prove answer quality.

Shadow Mode — a simulated baseline

Shadow Mode estimates what the same work would have cost without LeanCTX, without changing the active workflow. The baseline is simulated from the uncompressed token counts and the same outcome signals, not a second measured run, so its reports estimate cost, tokens and CPAO deltas; they do not measure answer quality.

LeanCTX records local cost and outcome signals without adding those reports to agent context. CPAO (cost per accepted outcome) is one comparison metric; Shadow Mode provides simulated savings estimates. Keep estimates, provider-measured usage and outcome quality separate.

lean-ctx savings --period week                 # costs, token savings, and CPAO
lean-ctx value-report --format markdown --last 20  # recent outcome quality
lean-ctx shadow --latest                       # latest baseline comparison

Quick start: usage tracking

# Enable shadow mode for savings comparison
lean-ctx config set shadow.enabled true

# After using LeanCTX for a while:
lean-ctx savings
lean-ctx shadow --latest

Feature overview (see generated MCP registry for the current count)

• Web & Research (ctx_url_read): pull a public web page, PDF, or YouTube transcript into context as compressed, citation-backed text — facts/quotes return claims with a confidence score + source URL, relevance-ranked research-compression distils to a token budget, SSRF-guarded (http/https only)