LeanCTX

// Overview

LeanCTX — short for Lean Context — is a local context-engineering layer that sits between a coding agent and the model. It runs alongside Cursor, Claude Code, Copilot, Windsurf, Codex, Gemini and 30-odd other agents with no configuration, and does four things to every request: understands the task, routes the right context, compresses what it sends, and tracks what that work cost and whether it was accepted. A local savings ledger and a Shadow Mode baseline report the measured result against a comparable uncompressed run, so the claim is checkable on your own workload rather than taken on faith.

Compression has two halves. File reads get ten modes — `full`, `map`, `signatures`, `diff`, `lines:N-M`, `density:X` and others — with cached re-reads returning a compact deterministic reference of roughly 13 tokens instead of the file again; `density:0.4` keeps the highest-entropy lines until about 40% of the original tokens remain, deterministically; and `signatures` carries line spans that point at `lines:N-M`, so an agent gets the outline first and pulls bodies on demand. Shell output gets 95+ patterns covering git, npm, cargo, docker, kubectl and terraform, plus 270 passthrough rules. A tree-sitter layer gives structural understanding for 27 languages, so this is AST-aware rather than text truncation.

Crucially the compression is reversible. Under content-addressed recovery, pruned or truncated payloads move to a content-addressed store behind a deterministic handle, and the model can pull the original bytes back through `ctx_expand`, `ctx_retrieve`, an in-band marker or `GET /v1/references/{id}` — five recovery paths, so nothing is silently discarded. On top of that sit session memory and a project knowledge graph that survive chat resets, impact analysis over a multi-edge property graph, a code-smell scanner, and a browser dashboard showing in real time what is occupying the context window. Everything is local-first and portable as a `.ctxpkg`; telemetry is opt-in only. It is written in Rust, Apache-2.0 licensed, and distributed through crates.io, npm, Homebrew and the AUR.

// What it does

• Ten file read modes including map, signatures, diff, lines:N-M and target density, with ~13-token cached re-reads
• 95+ shell-output compression patterns (git, npm, cargo, docker, kubectl, terraform) and 270 passthrough rules
• Tree-sitter AST understanding across 27 languages rather than plain text truncation
• Reversible by design — pruned payloads go to a content-addressed store with five recovery paths including ctx_expand and GET /v1/references/{id}
• Prompt-cache-safe proxy compression of each request, so compression does not invalidate the provider's cache
• Session memory and a project knowledge graph that persist across chats, with recall and consolidate commands
• Code intelligence — impact analysis over a multi-edge property graph and a code-smell scanner
• Local savings ledger, Shadow Mode baseline and a browser Context Manager dashboard; opt-in telemetry only

// Getting started

LeanCTX is a single binary with installers for shell, Homebrew, npm and Cargo. One wrap command registers the MCP server and configures the local transport for your agent; there are no config changes to make by hand.

curl -fsSL https://leanctx.com/install.sh | sh      # universal (no Rust needed)
brew tap yvgude/lean-ctx && brew install lean-ctx    # macOS / Linux
npm install -g lean-ctx-bin                          # Node.js
cargo install lean-ctx                               # Rust

lean-ctx wrap cursor      # or: wrap claude / wrap codex
lean-ctx doctor           # confirm you're wired up
lean-ctx gain             # tokens and USD saved, live

lean-ctx onboard          # connect all detected AI tools (zero prompts)
lean-ctx setup            # interactive wizard with every option

lean-ctx read src/server.rs -m map   # API surface, ~13 tok on re-read
lean-ctx -c "git status"             # compressed shell output
lean-ctx -c --raw "git status"       # one command, uncompressed

lean-ctx overview                    # task-aware project recap
lean-ctx knowledge recall "auth"     # facts that survive resets
lean-ctx knowledge consolidate       # import session + compact lifecycle

lean-ctx graph impact src/auth.rs    # blast radius
lean-ctx smells scan                 # code-smell hotspots

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Reach for it when a coding agent burns its context window re-reading the same files every turn
• Reach for it to cut the cost of noisy shell output — git, npm, cargo, docker — without losing the salient lines
• Reach for it when you need compression you can undo, with the original bytes recoverable on demand
• Reach for it to keep project knowledge and session memory local and portable across agents and model vendors

// How LeanCTX compares

LeanCTX alongside other open-source context compression & token budgets tools AI/TLDR tracks, ranked by GitHub stars.