lean-ctx (LeanCTX)

Core Positioning#

lean-ctx is positioned as "The Context OS for AI Development", focusing on context optimization during the "read" and "listen" phases of AI coding agents. It does not participate in code generation or execution logic, but works as an agent addon or underlying runtime.

Context Compression Engine#

• 10 read modes: auto, full, map, signatures, diff, aggressive, entropy, task, reference, lines:N-M
• AST-level parsing: Tree-sitter-based signature extraction for 18 programming languages
• Multi-strategy algorithms: Shannon entropy analysis, attention model (U-curve position weighting), TF-IDF codebook
• Extreme caching: cached re-reads down to ~13 tokens, overall token savings of 60–95%

Shell Output Processing#

• Transparent interception and compression of command output via Shell hook
• 56 built-in pattern modules covering git, npm, cargo, docker, fd, just, ninja, clang, etc.
• Compound lexer supporting &&, ||, and pipe-connected multi-command parsing

Code Property Graph#

• Multi-edge types: imports, calls, exports, type_ref, tested_by with weighted BFS traversal
• Incremental git-diff updates, re-indexing only changed files
• Graph-aware reads: each ctx_read automatically appends [related: ...] hints

Hybrid Search Engine#

• Three-way signal fusion: BM25 (lexical) + Dense Embeddings (ONNX all-MiniLM-L6-v2) + Graph Proximity (structural)
• RRF ranking: score = Σ 1/(60 + rank_i)

Session Memory & Knowledge Packaging#

• Persistent task/fact/decision storage; Session Survival Engine generates compaction snapshots
• Context Package System bundles Knowledge + Graph + Session + Patterns + Gotchas into .lctxpkg files
• SHA-256 integrity verification, cross-project/team sharing with intelligent merging

Governance & Security#

• Context Profiles: coder/bugfix/review/exploration/hotfix/ci-debug
• Role system, Token budgets, SLO evaluation, degradation strategies
• Secret/PII redaction, sandboxed execution (ctx_execute)
• Zero telemetry by default, optional anonymous statistics (opt-in)

Context Field Theory (CFT)#

• Unified potential function: Φ(i,t) = relevance + surprise + graph + history − cost − redundancy
• Greedy knapsack compiler + Boltzmann view selection

Architecture Overview#

• Single Rust binary (93.1% Rust), serving as both Shell Hook and MCP Server
• Entry layer: CLI (main.rs), MCP stdio, Streamable HTTP, daemon
• Service layer: LeanCtxServer + ToolRegistry (27 trait-based tools) + Pipeline Stages
• Intelligence core: dual-layer caching, multi-tokenizer support (o200k_base/cl100k_base/Gemini/Llama), Property Graph, ONNX inference, CFT compiler
• Local-first (code never leaves machine); prefix-cache-friendly output ordering; compression_safety semantic checks

Installation & Integration#

curl -fsSL https://leanctx.com/install.sh | sh
brew tap yvgude/lean-ctx && brew install lean-ctx
npm install -g lean-ctx-bin
cargo install lean-ctx
lean-ctx setup   # Auto-detect AI tools and configure shell hook + MCP
lean-ctx init --agent cursor|claude|copilot

Three integration modes: CLI-Redirect (zero MCP overhead), Hybrid (MCP caching + CLI shell/search), Full MCP (all 56 tools exposed via MCP).

Use Cases#

• AI-assisted development in medium-to-large repos/Monorepos (50+ files, significant context noise reduction)
• Shell-intensive workflows (git/test/build output compression)
• Cross-session continuity (persistent decisions and findings for long-term tasks)
• Team knowledge sharing (via Context Packages)
• Multi-agent collaboration (agent handoff, workflow orchestration)