LeanCTX Local Context Control
One local Rust binary that controls what your AI can see — compressing file reads and shell output and caching session context to cut token spend.
A context-compression tool; the install script is fetched and run via curl | bash from GitHub — a common but trust-the-maintainer install pattern; the tool wraps shell command execution.
What does this skill do, and when should you use it?
LeanCTX (lean-ctx) is a local context-intelligence layer for AI coding agents, running as a single Rust binary. It offers multiple file-read modes (full text down to signatures and entropy filtering), shell output compression, cached re-reads, and context recovery so agents read less and read smarter. This Skill document defines four tool-visibility profiles (Lean/minimal/standard/power), anchored file editing via ctx_read + ctx_patch, and architecture and verification tools invoked through ctx_call. The project is Apache-2.0 licensed, local-first, zero-config, and claims 60–90% token savings.
Replaces raw file reads with mode-based ctx_read (anchored, map, signatures, diff, lines:N-M, aggressive, entropy, task, auto), with re-reads served from a local cache (~13 tokens); wraps common commands (git, cargo, npm) with lean-ctx -c to compress their output; performs precise line-based editing via anchored views plus ctx_patch; exposes ctx_search, ctx_glob, ctx_tree, ctx_session, plus architecture tools (ctx_callgraph, ctx_impact, ctx_quality) and verification tools (ctx_verify, ctx_proof).
- Daily Cursor/Claude Code users repeatedly re-reading large files with high token bills, cutting read costs via cached re-reads and map/signatures modes
- Teams in shell-heavy workflows (git, tests, builds) compressing command output with the shell hook so the model sees only signal
- Engineers in large codebases (monorepos, 50+ files) using ctx_impact to gauge blast radius and ctx_callgraph to trace symbol calls
- Users letting agents make precise code edits through anchored reads + ctx_patch instead of full-file rewrites
- Context-budget-conscious users constraining which tools an agent can invoke via the four visibility profiles across the 76 MCP tools
What are this skill's strengths and limitations?
- Local-first single Rust binary, no telemetry by default, code never leaves the machine unless cloud sync is explicitly enabled
- Compression on both reads and shell output, ~13-token cached re-reads, with an auditable savings ledger and reproducible benchmarks
- Four tool-visibility profiles (Lean to power) narrow the advertised tool surface per client, reducing context overhead
- Works with 30+ agents including Cursor, Claude Code, Codex, Gemini CLI; one lean-ctx wrap command wires everything
- Payoff depends on three levers: window ownership, context lifetime, and provider pricing; small repos with little shell use land near break-even
- The 60–90% savings and ~13-token re-read figures are the project's own benchmarks; validate on your repos with lean-ctx benchmark
- Adds a layer of tool indirection: agents must learn ctx_* conventions and handle anchor CONFLICT retries
- README inconsistently cites 76/79/80/81 MCP tools across sections; actual tool count depends on version
How do you install this skill?
Install the binary: which lean-ctx || curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash, then run lean-ctx setup. Also available via brew, npm (lean-ctx-bin), cargo, or Pi (see README). The Skill lives at rust/src/templates/SKILL.md in the repo; the README does not specify where to place this Skill file within Claude Code.
How do you use this skill?
After setup, follow the SKILL.md workflow: run lean-ctx -c "git status" instead of raw shell exec; read files you will edit with ctx_read(mode="anchored"), then edit with ctx_patch(path, op, line, hash, new_text) — never reproduce old text byte-for-byte, batch via ops:[…], create new files with op=create. A stale anchor returns CONFLICT with fresh anchors (retry once). Full docs: https://leanctx.com/docs.
How does this skill compare with similar options?
The README positions LeanCTX on the same layer as standalone request-compression proxies such as Headroom — if its built-in proxy is enabled, you don't need Headroom on top; the official comparison page also lists RTK, Context+, and MemGPT.