| name | lean-ctx |
| description | Context Engineering for AI Agents — 79 MCP tools, 10 read modes, 95+ shell patterns, tree-sitter AST for 26 languages. Compresses LLM context by up to 99%. Use when reading files, running shell commands, searching code, or exploring directories. Auto-installs if not present. |
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:
which lean-ctx || bash scripts/install.sh
If the install script is not available locally, install manually:
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):
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 <command> 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 <command> 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
git status
git diff
git log --oneline -10
npm install
cargo build
cargo test
docker ps
kubectl get pods
aws ec2 describe-instances
helm list
prisma migrate dev
curl -s <url>
ls -la <dir>
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)
lean-ctx read <file>
lean-ctx read <file> -m map
lean-ctx read <file> -m signatures
lean-ctx read <file> -m aggressive
lean-ctx read <file> -m entropy
lean-ctx read <file> -m diff
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
lean-ctx init --global
lean-ctx init --agent cursor
lean-ctx init --agent claude
lean-ctx init --agent codebuddy
lean-ctx init --agent codex
lean-ctx init --agent opencode
lean-ctx init --agent copilot
lean-ctx init --agent jetbrains
lean-ctx init --agent windsurf
Multi-Agent & Knowledge
CLI (works in Hybrid and MCP setups):
lean-ctx knowledge remember "value" --category <c> --key <k>
lean-ctx knowledge recall "query"
lean-ctx knowledge search "query"
lean-ctx knowledge export [--format json|jsonl|simple] [--output <path>]
lean-ctx knowledge import <path> [--merge replace|append|skip-existing] [--dry-run]
lean-ctx knowledge remove --category <c> --key <k>
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 startctx_preload(task) — proactive context loader, caches task-relevant filesctx_semantic_search(query) — BM25 code search by meaning across the projectctx_intent now supports multi-intent detection and complexity classification- Semantic cache: TF-IDF + cosine similarity for finding similar files across reads
Session Continuity (CCP)
lean-ctx sessions list
lean-ctx sessions show
lean-ctx sessions delete <id>
lean-ctx wrapped
lean-ctx wrapped --month
lean-ctx benchmark run
lean-ctx benchmark run --json
lean-ctx benchmark 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 taskctx_session finding "file:line — summary" — record key findingctx_session decision "summary" — record architectural decisionctx_session save — force persist session to diskctx_gain action=wrapped — generate savings report card in chatctx_refactor — LSP-powered rename, references, definition, implementations (requires language server)ctx_expand action=search_all query="..." — FTS5 cross-archive fulltext search
Analytics
lean-ctx gain
lean-ctx dashboard
lean-ctx session
lean-ctx discover
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
