LeanCTX — Local Context Intelligence Layer
Select, shape, reuse, and recover context before your AI agent reads files or runs commands — one local Rust binary that cuts 60–90% of tokens.
Same as above, the formally released version — same curl | bash install and shell-command-wrapping capability.
What does this skill do, and when should you use it?
LeanCTX is a local context engineering layer for existing AI coding agents, shipped as a single local Rust binary. It compresses file reads and shell output through ten read modes, 95+ command-output patterns, semantic caching, and cross-chat session memory. It supports two integration styles — Hybrid (MCP tools plus shell hooks) and pure MCP — auto-detected per agent, covering Cursor, Claude Code, Codex, and 30+ others. Everything stays local by default with no telemetry, and savings are measurable via lean-ctx gain. This skill corresponds specifically to skills/lean-ctx/SKILL.md within the repository.
Reads files and presents them in selectable modes (map: dependency graph/API surface, signatures, aggressive syntax-stripped, entropy-filtered, diff-since-last-read); intercepts and compresses shell command output for git, npm, cargo, docker, kubectl, terraform and 95+ other patterns; provides a local knowledge store with remember/recall/search/import/export; persists and restores session state (tasks, findings, decisions) across chats; offers BM25 semantic code search, anchored editing via ctx_patch, project overviews, and a live context-usage dashboard.
- A developer coding daily in a large repo with Cursor or Claude Code who keeps re-reading the same files — cached re-reads cost about 13 tokens
- An agent-heavy workflow running verbose git diffs, tests, and builds that should be auto-compressed before reaching the model
- An engineer whose long sessions get compacted or who opens new chats and needs session/knowledge to restore tasks, decisions, and findings
- Someone onboarding into an unfamiliar codebase who wants map/signatures views of the API surface without reading full files
- A cost-conscious user who wants lean-ctx gain and the dashboard to see and budget context usage in real time
- A JetBrains or VS Code user without reliable shell hooks, wiring all tools through the MCP-only mode instead
What are this skill's strengths and limitations?
- Measured, reproducible compression: README benchmarks show ~98% for map mode and ~13-token cached re-reads, with built-in benchmark/doctor tooling to verify locally
- Local-first with no telemetry by default; code never leaves the machine unless you opt into cloud sync; Apache-2.0 licensed
- Session and knowledge memory persist across chats and export as portable .ctxpkg packages
- Broad compatibility: a standard MCP server with auto-detected setup for 30+ agents
- Reversible by design (CCR): compressed content can be pulled back to original bytes on demand
- Requires installing and configuring a local binary; setup/wrap modifies shell and editor configs, and removal needs a dedicated command
- Payoff depends on the scenario — README itself admits near break-even for tiny repos with few shell calls
- No hands-on evidence for untested agents/platforms; API-only compatibility is inferred from documentation
- Some features are explicitly experimental (local collaboration tools are outside the default public runtime surface)
- Compression is lossy — even with recovery paths, original output requires an extra retrieval step
How do you install this skill?
1) Install the binary: curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash, or brew install lean-ctx / npm install -g lean-ctx-bin / cargo install lean-ctx. 2) Run lean-ctx setup for one-command configuration (shell hook + editor wiring + rules + skills). The skill file lives at skills/lean-ctx/SKILL.md in the repo; place it in your agent's skills directory — the README does not document a specific target-folder convention.
How do you use this skill?
Once installed, agents use it automatically: lean-ctx read <file> -m map for structure-only reads; lean-ctx -c "git status" for compressed command output; lean-ctx knowledge remember/recall for memory; lean-ctx session save to persist state; lean-ctx gain to view savings. Wire a specific agent with lean-ctx init --agent cursor|claude|codex|copilot, etc. To force skill use, ask the agent in a prompt to run lean-ctx read before reading files.
How does this skill compare with similar options?
The README compares itself to RTK, Context+, and MemGPT (see leanctx.com/compare); it also functions as the same layer as standalone request-compression proxies like Headroom — using it means you don't need a separate proxy on top.