# LeanCTX

> Local context gate that compresses file reads and shell output for coding agents

- Category: App Orchestration / Context Compression & Token Budgets
- Language: Rust
- Licence: Apache-2.0
- Repository: https://github.com/yvgude/lean-ctx
- Website: https://leanctx.com
- Canonical page: https://ai-tldr.dev/tools/lean-ctx/

## In short

LeanCTX — short for Lean Context — is a local context-engineering layer that sits between a coding agent and the model. It sits in the Context Compression & Token Budgets category of the App Orchestration tools and is open-source, written in Rust and licensed Apache-2.0. To get started: install.

## 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.

1. Install

   Pick whichever channel suits the machine — the universal installer needs no Rust toolchain.

```bash
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
```

2. Wire up your agent

   wrap registers the MCP server and the supported local transport for that agent; unwrap reverses it. Note that Claude Pro/Max subscription OAuth cannot use a custom ANTHROPIC_BASE_URL, so `wrap claude` enables the ctx_* tools and shell-output compression without adding a proxy redirect.

```bash
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
```

3. Or connect everything at once

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

4. Use it day to day

   Read files through LeanCTX to get the compressed view, and run shell commands with -c to compress their output.

```bash
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
```

5. Carry context across chats

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

6. Understand a codebase

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

## 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