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.

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.

What is LeanCTX? · Where LeanCTX fits · Architecture

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.

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 instead of a larger prompt.

• Session memory (CCP): persist task/facts/decisions across chats — structured recovery queries survive compaction
• Knowledge graph: temporal facts with validity windows, episodic + procedural memory
• Property Graph: multi-edge code graph (imports, calls, exports, type_ref) powers impact analysis and search ranking
• Yours, not the vendor's: memory stays local and portable — export it as a .ctxpkg package and move it across machines or models, instead of locking it in a vendor's black box

4. Usage and outcome evidence

Performance is the cost of a useful result, not just speed. LeanCTX records costs and outcomes locally; CPAO (Cost per Accepted Outcome) is the north-star metric for comparing useful AI work.

• Context Manager: browser dashboard with real-time token tracking, compression stats, utilization gauge
• Budgets & SLOs: profiles, roles, per-agent budgets, and throttling policies
• 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)

5. Shadow Recommendations — savings proof

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