# LeanCTX Feature Catalog (SSOT Snapshot) **Version:** `3.8.1` **Updated:** `2026-05-15` **Primary Sources:** `website/generated/mcp-tools.json`, `rust/src/tool_defs/granular.rs`, `README.md` --- ## Purpose This catalog is the single feature inventory for LeanCTX at release/runtime level: - Which MCP tools exist now - Which entry points are canonical vs deprecated aliases - Which read modes are supported - Which shell pattern modules exist - Which CLI commands are available - Which capabilities are part of the shipped product surface --- ## Runtime Surface (Current) - Granular MCP tools: **81** - Unified MCP tools: **5** - MCP Resources: **5** - MCP Prompts: **5** - Dynamic Tool Categories: **6** - Shell pattern modules: **56** (fd, just, ninja, clang, extended cargo run/bench added in 3.4.x) - CLI commands: **80+** (knowledge, overview, compress, serve --daemon/--stop/--status, session, pack create/list/info/export/import/install/remove/auto-load subcommands added in 3.4.x) - Read modes: **10** (`auto`, `full`, `map`, `signatures`, `diff`, `aggressive`, `entropy`, `task`, `reference`, `lines:N-M`) - Positioning: Context Runtime for AI agents (shell hook + context server + setup integrations) --- ## Unified MCP Tools (5) - `ctx` - `ctx_read` - `ctx_search` - `ctx_shell` - `ctx_tree` --- ## Granular MCP Tools (81) ### A) Read / Search / IO Surface - `ctx_read` - `ctx_multi_read` - `ctx_smart_read` - `ctx_tree` - `ctx_search` - `ctx_semantic_search` - `ctx_shell` - `shell` _(alias of `ctx_shell` — gives Codex Desktop/Cloud the same shell-output compression; registered for all MCP clients)_ - `ctx_edit` - `ctx_patch` _(hash-anchored line edits — `LINE:HASH` anchors from `ctx_read mode=anchored`, no exact-recall)_ - `ctx_delta` - `ctx_dedup` - `ctx_fill` - `ctx_outline` - `ctx_symbol` - `ctx_routes` - `ctx_context` - `ctx_compose` - `ctx_explore` _(FastContext-style bounded multi-turn exploration → `path:start-end` citations; locates code across files at a fraction of `ctx_compose`'s tokens)_ ### B) Architecture / Analysis / Discovery - `ctx_graph` _(actions: build, related, symbol, impact, status, enrich, context, diagram)_ - `ctx_callgraph` _(direction=callers|callees)_ - `ctx_refactor` _(LSP: rename, references, definition, implementations)_ - `ctx_architecture` - `ctx_impact` - `ctx_quality` _(navigability score + cognitive-complexity hotspots + estimated token "quality tax"; agent twin of `lean-ctx health`)_ - `ctx_review` - `ctx_pack` - `ctx_index` - `ctx_artifacts` - `ctx_intent` - `ctx_task` - `ctx_overview` - `ctx_preload` - `ctx_prefetch` - `ctx_discover` - `ctx_analyze` ### C) Session / Knowledge / Multi-Agent - `ctx_session` - `ctx_knowledge` - `ctx_agent` - `ctx_share` - `ctx_handoff` - `ctx_workflow` - `ctx_feedback` #### Knowledge CLI (`lean-ctx knowledge`) Full CLI parity with MCP `ctx_knowledge`: - `remember --category --key ` — store a fact - `recall [query] [--category ] [--mode auto|semantic|hybrid]` — retrieve facts - `search ` — cross-project knowledge search - `export [--format json|jsonl|simple] [--output ]` — export knowledge (stdout or file) - `import [--merge replace|append|skip-existing] [--dry-run]` — import from JSON/JSONL - `remove --category --key ` — remove a fact - `consolidate [--all]` — import latest session if present, run lifecycle, then leave 25% facts/history/procedures capacity free; `--all` repeats this for every stored project root - `status` — knowledge base summary - `health` — health report with quality metrics - `lifecycle` — read-only lifecycle/capacity report Import supports three formats: native `ProjectKnowledge` JSON, simple `[{category, key, value}]` array, and JSONL (one fact per line). The `simple` format serves as the community interop schema for migration from other tools. ### D) Compression / Metrics / Runtime Ops - `ctx_cache` - `ctx_compress` - `ctx_expand` _(actions: retrieve, list, search_all — FTS5 cross-archive fulltext search)_ - `ctx_call` - `ctx_compress_memory` - `ctx_metrics` - `ctx_cost` - `ctx_heatmap` - `ctx_gain` _(actions: wrapped, summary, delta)_ - `ctx_execute` - `ctx_benchmark` - `ctx_compare` _(preview compression — original vs the bytes lean-ctx would emit + token counts and line diff, read-only)_ - `ctx_response` - `ctx_tools` _(MCP Tool-Catalog Gateway — actions: find, call, list, refresh; routes/proxies unlimited downstream MCP servers at constant context cost)_ --- ## MCP Protocol Capabilities ### MCP Resources (5) Subscribe-capable resources, gated by client capabilities: - `lean-ctx://context/summary` - `lean-ctx://context/pressure` - `lean-ctx://context/plan` - `lean-ctx://context/pinned` - `lean-ctx://context/bounce` ### MCP Prompts (5) Appear as slash commands in supporting IDEs: - `/context-focus` - `/context-review` - `/context-reset` - `/context-pin` - `/context-budget` ### Elicitation Rate-limited context decisions triggered by: - Pressure >90% - Large files >5k tok - Budget exhaustion Fallback hints emitted for non-supporting IDEs. ### Dynamic Tool Categories (6) On-demand loading via `ctx_load_tools` + `notifications/tools/list_changed`: - **core** (~27 tools, always loaded) - **arch** - **debug** - **memory** - **metrics** - **session** `ctx_load_tools` _(actions: load, unload, list)_ — explicit category management at runtime. After each change, `notifications/tools/list_changed` is sent to subscribed clients. --- ## Intelligence Layer ### Context Gate (Active) Pre-dispatch mode override: - **Overlay override** (pin/exclude/set_view) - **Pressure-based auto-downgrade** (ForceCompression: full→map, EvictLeastRelevant: map→signatures) - Bounce-prevention - Intent-target (with real task from SessionState) - Graph-proximity - Knowledge-relevance Post-dispatch: - Ledger recording (with real task Φ computation) - Reinjection plan (downgrade existing "full" entries to "map" under pressure) - Eviction/elicitation hints - `notifications/resources/updated` on significant ledger changes ### Bounce Detection Tracks wasted tokens from compressed→full re-reads: - Per-extension bounce rates - Adjusts savings metrics to report honest numbers ### Client Capability Detection Runtime detection of 9 IDE clients: - Cursor, Claude Code, CodeBuddy, Windsurf, Zed, VS Code Copilot, Kiro, Codex, Antigravity, Gemini CLI Tier 1–4 classification determines feature gating for resources, prompts, elicitation, and dynamic tools. --- ## Removed Aliases (v3.6.1+) Previously deprecated aliases have been removed. Use the canonical tools: - `ctx_callgraph direction=callers` (was: ctx_callers) - `ctx_callgraph direction=callees` (was: ctx_callees) - `ctx_graph action=diagram` (was: ctx_graph_diagram) - `ctx_gain action=wrapped` (was: ctx_wrapped) --- ## Capabilities (3.4.x Additions) ### Daemon Mode - Unix Domain Socket server via `lean-ctx serve --daemon` - Control via `--stop`, `--status` flags - Persistent background process for lower-latency MCP serving ### Multi-Tokenizer Support - `o200k_base` (GPT-4o, default) - `cl100k_base` (GPT-4 / GPT-3.5) - Gemini tokenizer - Llama tokenizer ### Hook Modes - `HookMode::Mcp` — MCP server only (IDE-extension agents without reliable shell hooks) - `HookMode::Hybrid` — MCP server + shell hooks (default where shell access exists) ### Smart Mode Selection in Setup - `lean-ctx setup` auto-detects editor and agent, selects optimal hook mode ### SKILL.md Auto-Installation - `lean-ctx init` writes `SKILL.md` to agent-specific skill directories - Auto-detects Cursor, Claude Code, CodeBuddy, Codex, Gemini CLI, Kiro skill paths ### Compressed Output Cache - `map` and `signatures` read modes cache compressed output - Re-reads of compressed representations cost ~13 tokens ### Intent-Aware Read Mode Selection - `ctx_read mode=auto` uses task intent to select optimal compression - Factors: file type, file size, task signal, access history ### Prefix-Cache-Friendly Output Ordering - Imports and type definitions emitted before function bodies - Stable ordering maximizes LLM provider KV-cache hits ### Field-Wise Profile Merge - Context profiles merged field-by-field (not replaced wholesale) - Allows layered profile composition (base + project + role) ### Token Counting Deduplication - Cross-file shared block detection via `ctx_dedup` - Deduplicated blocks counted once in budget calculations ### Graph-Powered Context OS (3.4.7) #### Multi-Edge Graph Queries - Property Graph queries traverse `imports`, `calls`, `exports`, `type_ref`, `tested_by` - Weighted BFS: imports=1.0, calls=0.8, exports=0.7, type_ref=0.5, tested_by=0.4 - New query: `related_files(path, limit)` — scored file neighbors - New query: `file_connectivity(path)` — edge-type breakdown per file #### Graph-Aware File Reads - Every `ctx_read` includes a `[related: ...]` hint from the Property Graph - Scored related files shown with relationship strength (e.g., `config.rs (80%)`) - Agent understands file context immediately without extra tool calls #### Calls + Exports Edge Materialization - Graph build writes `EdgeKind::Calls` edges (symbol-to-symbol and file-to-file) - Graph build writes `EdgeKind::Exports` for exported symbols (symbol-to-file) - Impact analysis now tracks function-level blast radius, not just file-level #### Incremental Graph Update - `ctx_impact action="update"` uses `git diff --name-only` to detect changed files - Only changed files are re-indexed (remove_file_nodes + re-parse) - Deleted files have their nodes removed automatically - Full build hints when incremental update is available #### Session Survival Engine - `build_compaction_snapshot()` generates structured recovery XML: - ``: executable `ctx_read`/`ctx_search` commands - ``: `ctx_knowledge recall` queries from task keywords - ``: dependency cluster references for touched files - Budget-aware with automatic section shrinking #### Knowledge-Enriched Overview - `ctx_overview` includes top relevant Knowledge facts for the current task - Graph architectural hotspots: files ranked by edge count (imports + calls) #### Hybrid Search Fusion (RRF) - `ctx_semantic_search` combines 3 signals via Reciprocal Rank Fusion: - BM25 (lexical), Dense Embeddings (semantic), Graph Proximity (structural) - `score = sum(1 / (60 + rank_i))` over all signals - Graph neighbors of recently touched files get score boost #### Progressive Search Throttling - Per-session tracker for repeated pattern+path combinations - Calls 1-3: normal, 4-6: hint to use `ctx_knowledge remember`, 7+: throttle hint - Auto-reset after 5 minutes idle #### Sandbox-First Routing - `ctx_shell` output >5KB: hint to use `ctx_execute` for compression - `ctx_read` full mode >10K tokens: hint to use `map`/`aggressive` - Once-per-session deduplication #### Terse Mode - `ctx_session action="configure" terse=true` enables concise response mode - Injects instruction into resume block: focus on code/actions, avoid filler - Survives context compaction via snapshot #### Context Package System (3.4.7) Context packages bundle Knowledge, Graph, Session, Patterns, and Gotchas into portable `.ctxpkg` files that can be shared, versioned, and auto-loaded across projects. ##### Package Layers - **Knowledge**: facts, patterns, consolidated insights from ProjectKnowledge - **Graph**: nodes + edges from the Property Graph (full SQLite export) - **Session**: task description, findings, decisions, next steps, files touched - **Patterns**: project patterns extracted from knowledge - **Gotchas**: gotcha entries with triggers, resolutions, file patterns ##### CLI Commands (9 subcommands under `lean-ctx pack`) - `create` — build package from current project context (knowledge, graph, session, gotchas) - `list` — list all installed packages with layers, size, auto-load status - `info` — detailed package view (stats, integrity, provenance, estimated tokens) - `remove` — remove package from local registry - `export` — export to portable `.ctxpkg` file (JSON bundle with SHA-256 integrity) - `import` — import from `.ctxpkg` file into local registry - `install` — apply package to current project (merge knowledge, import graph, import gotchas) - `auto-load` — enable/disable automatic loading on `ctx_overview` session start - `pr` — existing PR context pack (unchanged) ##### Premium Features - **SHA-256 Content Integrity**: canonical compact JSON hashing, verified on every load - **Atomic Writes**: tmp + rename pattern prevents corruption - **Knowledge Merge**: duplicate detection (category + key + value), confidence capped at 0.8 for imports - **Graph Overlay**: nodes and edges imported directly into the SQLite Property Graph - **Gotcha Import**: ID-based dedup, severity mapping, confidence capping - **Auto-Load**: packages flagged `auto_load=true` loaded on every `ctx_overview` call - **Schema Versioning**: `CONTEXT_PACKAGE_V1_SCHEMA_VERSION` in `contracts.rs` - **Compression Stats**: gzip-based compression ratio tracked in manifest --- ## Notes For Releases - Tool counts and tool names must match `website/generated/mcp-tools.json`. - Shell pattern module count must match `rust/src/core/patterns/mod.rs` module list. - Any new tool or alias change requires synchronized updates in: - `README.md` and relevant package READMEs - `rust/src/templates/*` where applicable - this catalog - Historical counts in old CHANGELOG entries remain unchanged by design.