--- name: LeanCTX slug: leanctx category: AI Engineering description: LeanCTX compresses LLM context by up to 99% using 79 MCP tools, 10 read modes, 95+ shell compression patterns, and tree-sitter AST parsing for 26 languages. Use it when reading files, running shell commands, searching code, or exploring directories. github: "https://github.com/yvgude/lean-ctx/tree/main/skills/lean-ctx" language: Rust stars: 3582 forks: 324 install: "npx degit https://github.com/yvgude/lean-ctx/tree/main/skills/lean-ctx ~/.claude/skills/lean-ctx" installs_to: ~/.claude/skills/lean-ctx source_path: skills/lean-ctx/SKILL.md collection_size: 2 category_size: 2451 collection_url: "https://dirskills.com/collections/yvgude/lean-ctx" added: 2026-08-16T07:02:20.814Z last_synced: 2026-08-16T07:02:20.814Z canonical_url: "https://dirskills.com/skills/leanctx" --- # LeanCTX LeanCTX compresses LLM context by up to 99% using 79 MCP tools, 10 read modes, 95+ shell compression patterns, and tree-sitter AST parsing for 26 languages. Use it when reading files, running shell commands, searching code, or exploring directories. **Install:** ```bash npx degit https://github.com/yvgude/lean-ctx/tree/main/skills/lean-ctx ~/.claude/skills/lean-ctx ``` ## README # LeanCTX — Context Engineering for AI Agents LeanCTX optimizes LLM context through 79 MCP tools, 95+ shell compression patterns, and tree-sitter AST parsing for 26 languages. It provides adaptive file reading, cross-session memory (CCP), task-conditioned relevance scoring, and a feedback loop for learning optimal compression. ## Setup (run first) Before using lean-ctx, verify it is installed: ```bash which lean-ctx || bash scripts/install.sh ``` If the install script is not available locally, install manually: ```bash curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash ``` After installation, run the one-command setup (installs shell hook + editor wiring + rules + skills): ```bash lean-ctx setup ``` lean-ctx supports two integration styles (auto-detected per agent): - **Hybrid (default where shell access exists)**: MCP for cached reads/search + shell hooks that compress command output. - **MCP (for IDE-extension agents without reliable shell hooks)**: cached reads + all tools via MCP. ## When to use lean-ctx Prefer the current shell's configured compression over nested wrappers. In agent shells, run commands normally unless the user explicitly asks for `lean-ctx -c ` or task setup/docs explicitly say the shell is not wrapped. Do not inspect env vars just to decide; users may forbid env access. Use `lean-ctx -c ` over running commands directly only when: - The command produces verbose output (build logs, git diffs, dependency trees, test results) - You are reading files and only need the structure or API surface - You want to check token savings for the current session ## Shell commands ```bash git status # Compressed by configured agent shell/wrapper git diff # Meaningful diff lines when configured git log --oneline -10 npm install # Strips progress bars/noise when configured cargo build cargo test docker ps kubectl get pods aws ec2 describe-instances helm list prisma migrate dev curl -s # JSON schema extraction ls -la # Grouped directory listing # Explicit user request / documented unwrapped shell: lean-ctx -c "git status" ``` Supported: git, npm, pnpm, yarn, bun, deno, cargo, docker, kubectl, helm, gh, pip, ruff, go, eslint, prettier, tsc, aws, psql, mysql, prisma, swift, zig, cmake, ansible, composer, mix, bazel, systemd, terraform, make, maven, dotnet, flutter, poetry, rubocop, playwright, curl, wget, and more. ## File reading (compressed modes) ```bash lean-ctx read # Full content with structured header lean-ctx read -m map # Dependency graph + exports + API (~5-15% tokens) lean-ctx read -m signatures # Function/class signatures only (~10-20% tokens) lean-ctx read -m aggressive # Syntax-stripped (~30-50% tokens) lean-ctx read -m entropy # Shannon entropy filtered (~20-40% tokens) lean-ctx read -m diff # Only changed lines since last read ``` Use `map` mode when you need to understand what a file does without reading every line. Use `signatures` mode when you need the API surface of a module (tree-sitter for 26 languages). Use `anchored` mode (MCP: `ctx_read(mode="anchored")`) when you will edit the file — it adds `N:hh|` anchors so `ctx_patch` can edit by reference without echoing old text. ## AI Tool Integration ```bash lean-ctx init --global # Install shell aliases lean-ctx init --agent cursor # Hybrid (MCP reads/search + shell hooks) lean-ctx init --agent claude # Hybrid (Claude Code) lean-ctx init --agent codebuddy # Hybrid (CodeBuddy) lean-ctx init --agent codex # Hybrid (Codex CLI) lean-ctx init --agent opencode # Hybrid (OpenCode) lean-ctx init --agent copilot # MCP (VS Code / Copilot) lean-ctx init --agent jetbrains # MCP (JetBrains) lean-ctx init --agent windsurf # Hybrid (Windsurf) # Mode is auto-detected; override with --mode mcp|hybrid if needed. ``` ## Multi-Agent & Knowledge CLI (works in Hybrid and MCP setups): ```bash lean-ctx knowledge remember "value" --category --key lean-ctx knowledge recall "query" lean-ctx knowledge search "query" lean-ctx knowledge export [--format json|jsonl|simple] [--output ] lean-ctx knowledge import [--merge replace|append|skip-existing] [--dry-run] lean-ctx knowledge remove --category --key lean-ctx knowledge consolidate [--all] lean-ctx session task "what you're doing" lean-ctx session finding "what you found" lean-ctx session decision "what you decided" lean-ctx session save ``` If MCP is enabled for your IDE, the same capabilities are also available as MCP tools (`ctx_knowledge`, `ctx_session`, `ctx_agent`, ...). ## Additional Intelligence Tools - `ctx_patch(path, ops)` — anchored editing: `N:hh|` line+hash anchors from `ctx_read(mode="anchored")`, batch-atomic, `op=create` for new files (`ctx_edit` is the legacy str-replace fallback) - `ctx_overview(task)` — task-relevant project map at session start - `ctx_preload(task)` — proactive context loader, caches task-relevant files - `ctx_semantic_search(query)` — BM25 code search by meaning across the project - `ctx_intent` now supports multi-intent detection and complexity classification - Semantic cache: TF-IDF + cosine similarity for finding similar files across reads ## Session Continuity (CCP) ```bash lean-ctx sessions list # List all CCP sessions lean-ctx sessions show # Show latest session state lean-ctx sessions delete # Delete one saved session lean-ctx wrapped # Weekly savings report card lean-ctx wrapped --month # Monthly savings report card lean-ctx benchmark run # Real project benchmark (terminal output) lean-ctx benchmark run --json # Machine-readable JSON output lean-ctx benchmark report # Shareable Markdown report ``` MCP tools for CCP: - `ctx_session status` — show current session state (~400 tokens) - `ctx_session load` — restore previous session (cross-chat memory) - `ctx_session task "description"` — set current task - `ctx_session finding "file:line — summary"` — record key finding - `ctx_session decision "summary"` — record architectural decision - `ctx_session save` — force persist session to disk - `ctx_gain action=wrapped` — generate savings report card in chat - `ctx_refactor` — LSP-powered rename, references, definition, implementations (requires language server) - `ctx_expand action=search_all query="..."` — FTS5 cross-archive fulltext search ## Analytics ```bash lean-ctx gain # Visual token savings dashboard lean-ctx dashboard # Web dashboard at localhost:3333 lean-ctx session # Adoption statistics lean-ctx discover # Find uncompressed commands in shell history ``` ## Tips - The output suffix `[lean-ctx: 5029→197 tok, -96%]` shows original vs compressed token count - For large outputs, lean-ctx automatically truncates while preserving relevant context - JSON responses from curl/wget are reduced to schema outlines - Build errors are grouped by type with counts - Test results show only failures with summary counts - Cached re-reads cost only ~13 tokens