Hybrid Context Optimizer with Token Dense Dialect (TDD). Shell Hook + MCP Server. tree-sitter AST parsing for 14 languages. Single Rust binary.
Website · Install · Quick Start · CLI Reference · MCP Tools · TDD · Dashboard · Editor Setup · vs RTK · Discord · Claude Code One-Shot Setup
lean-ctx reduces LLM token consumption by up to 99% through two complementary strategies in a single binary:
- Shell Hook — Transparently compresses CLI output before it reaches the LLM. Works without LLM cooperation.
- MCP Server — 10 tools for cached file reads, dependency maps, cache management, entropy analysis, and session metrics. Works with Cursor, GitHub Copilot, Claude Code, Windsurf, OpenAI Codex, Google Antigravity, OpenCode, and any MCP-compatible editor. Shell hook also benefits OpenClaw via transparent compression.
| Operation | Frequency | Standard | lean-ctx | Savings |
|---|---|---|---|---|
| File reads (cached) | 15x | 30,000 | 195 | -99% |
| File reads (map mode) | 10x | 20,000 | 2,000 | -90% |
| ls / find | 8x | 6,400 | 1,280 | -80% |
| git status/log/diff | 10x | 8,000 | 2,400 | -70% |
| grep / rg | 5x | 8,000 | 2,400 | -70% |
| cargo/npm build | 5x | 5,000 | 1,000 | -80% |
| Test runners | 4x | 10,000 | 1,000 | -90% |
| curl (JSON) | 3x | 1,500 | 165 | -89% |
| docker ps/build | 3x | 900 | 180 | -80% |
| Total | ~89,800 | ~10,620 | -88% |
Estimates based on medium-sized TypeScript/Rust projects. MCP cache hits reduce re-reads to ~13 tokens each.
brew tap yvgude/lean-ctx
brew install lean-ctxyay -S lean-ctx # builds from source (crates.io)
# or
yay -S lean-ctx-bin # pre-built binary (GitHub Releases)cargo install lean-ctx# Option 1: Download from GitHub Releases
# Download lean-ctx-x86_64-pc-windows-msvc.zip from
# https://github.com/yvgude/lean-ctx/releases/latest
# Extract and add to PATH
# Option 2: Cargo
cargo install lean-ctx
# Option 3: Build from source
git clone https://github.com/yvgude/lean-ctx.git
cd lean-ctx/rust
cargo build --release
# Binary: target\release\lean-ctx.exegit clone https://github.com/yvgude/lean-ctx.git
cd lean-ctx/rust
cargo build --release
cp target/release/lean-ctx ~/.local/bin/ # macOS/Linux
# Windows: copy target\release\lean-ctx.exe to a directory in your PATHAdd
~/.local/binto your PATH if needed (macOS/Linux):echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
lean-ctx --version # Should show "lean-ctx 1.8.2"
lean-ctx gain # Should show token savings statslean-ctx introduces TDD mode — enabled by default. TDD compresses LLM communication using mathematical symbols and short identifiers:
| Symbol | Meaning |
|---|---|
λ |
function/handler |
§ |
struct/class/module |
∂ |
interface/trait |
τ |
type alias |
ε |
enum |
α1, α2... |
short identifier IDs |
How it works:
- Signatures use compact notation:
λ+handle(⊕,path:s)→sinstead offn pub async handle(&self, path: String) -> String - Long identifiers (>12 chars) are mapped to
α1, α2...with a§MAPat the end - MCP instructions tell the LLM to respond in Token Dense Dialect — shorter responses, less thinking tokens
Result: 8-25% additional savings on top of existing compression.
Configure with LEAN_CTX_CRP_MODE:
tdd(default) — Maximum compression with symbol shorthandcompact— Moderate: skip filler words, use abbreviationsoff— Standard output, no CRP instructions
# 1. Install
cargo install lean-ctx
# 2. Set up shell hook (auto-installs aliases)
lean-ctx init --global
# 3. Configure your editor (example: Cursor)
# Add to ~/.cursor/mcp.json:
# { "mcpServers": { "lean-ctx": { "command": "lean-ctx" } } }
# 4. Restart your shell + editor, then test
git status # Automatically compressed via shell hook
lean-ctx gain # Check your savingsThe shell hook transparently wraps commands (e.g., git status → lean-ctx -c git status) and compresses the output. The LLM never sees the rewrite — it just gets compact output.
Without lean-ctx: With lean-ctx:
LLM --"read auth.ts"--> Editor --> File LLM --"ctx_read auth.ts"--> lean-ctx --> File
^ | ^ | |
| ~2,000 tokens (full file) | | ~13 tokens (cached) | cache+hash |
+----------------------------------+ +------ (compressed) -------+------------+
LLM --"git status"--> Shell --> git LLM --"git status"--> lean-ctx --> git
^ | ^ | |
| ~800 tokens (raw output) | | ~150 tokens | compress |
+---------------------------------+ +------ (filtered) -----+--------------+
Four strategies applied per command type:
- Smart Filtering — Removes noise (progress bars, ANSI codes, whitespace, boilerplate)
- Grouping — Aggregates similar items (files by directory, errors by type)
- Truncation — Keeps relevant context, cuts redundancy
- Deduplication — Collapses repeated log lines with counts
lean-ctx -c "git status" # Execute + compress output
lean-ctx exec "cargo build" # Same as -c
lean-ctx shell # Interactive REPL with compressionlean-ctx read file.rs # Full content (with structured header)
lean-ctx read file.rs -m map # Dependency graph + API signatures (~10% tokens)
lean-ctx read file.rs -m signatures # Function/class signatures only (~15% tokens)
lean-ctx read file.rs -m aggressive # Syntax-stripped content (~40% tokens)
lean-ctx read file.rs -m entropy # Shannon entropy filtered (~30% tokens)
lean-ctx read file.rs -m "lines:10-50,80-90" # Specific line ranges (comma-separated)
lean-ctx diff file1.rs file2.rs # Compressed file diff
lean-ctx grep "pattern" src/ # Grouped search results
lean-ctx find "*.rs" src/ # Compact find results
lean-ctx ls src/ # Token-optimized directory listing
lean-ctx deps . # Project dependencies summarylean-ctx init --global # Install 23 shell aliases (zsh/bash/fish/PowerShell)
lean-ctx gain # Persistent token savings (CLI)
lean-ctx gain --graph # ASCII chart of last 30 days
lean-ctx gain --daily # Day-by-day breakdown
lean-ctx gain --json # Raw JSON export of all stats
lean-ctx dashboard # Web dashboard at localhost:3333
lean-ctx dashboard --port=8080 # Custom port
lean-ctx discover # Find uncompressed commands in shell history
lean-ctx session # Show adoption statistics
lean-ctx config # Show configuration (~/.lean-ctx/config.toml)
lean-ctx config init # Create default config file
lean-ctx doctor # Diagnostics: PATH, config, aliases, MCP, ports
lean-ctx --version # Show version
lean-ctx --help # Full helplean-ctx # Start MCP server (stdio) — used by editorsThe shell hook applies pattern-based compression for 75+ commands across 19 categories:
| Category | Commands | Savings |
|---|---|---|
| Git (19) | status, log, diff, add, commit, push, pull, fetch, clone, branch, checkout, switch, merge, stash, tag, reset, remote, blame, cherry-pick | -70-95% |
| Docker (10) | build, ps, images, logs, compose ps/up/down, exec, network, volume, inspect | -70-90% |
| npm/pnpm/yarn (6) | install, test, run, list, outdated, audit | -70-90% |
| Cargo (3) | build, test, clippy | -80% |
| GitHub CLI (9) | pr list/view/create/merge, issue list/view/create, run list/view | -60-80% |
| Kubernetes (8) | get pods/services/deployments, logs, describe, apply, delete, exec, top, rollout | -60-85% |
| Python (7) | pip install/list/outdated/uninstall/check, ruff check/format | -60-80% |
| Ruby (4) | rubocop, bundle install/update, rake test, rails test (minitest) | -60-85% |
| Linters (4) | eslint, biome, prettier, stylelint | -60-70% |
| Build Tools (3) | tsc, next build, vite build | -60-80% |
| Test Runners (8) | jest, vitest, pytest, go test, playwright, cypress, rspec, minitest | -90% |
| Terraform | init, plan, apply, destroy, validate, fmt, state, import, workspace | -60-85% |
| Make | make targets, parallel jobs (-j), dry-run (-n) |
-60-80% |
| Maven / Gradle | compile, test, package, install, clean, dependency trees | -60-85% |
| .NET | dotnet build, test, restore, run, publish, pack |
-60-85% |
| Flutter / Dart | flutter pub, analyze, test, build; dart pub, analyze, test | -60-85% |
| Poetry / uv | install, sync, lock, run, add, remove; uv pip/sync/run | -60-85% |
| Utils (5) | curl, grep/rg, find, ls, wget | -50-89% |
| Data (3) | env (filtered), JSON schema extraction, log deduplication | -50-80% |
Unrecognized commands get generic compression: ANSI stripping, empty line removal, and long output truncation.
After lean-ctx init --global, these commands are transparently compressed:
git, npm, pnpm, yarn, cargo, docker, docker-compose, kubectl, k,
gh, pip, pip3, ruff, go, golangci-lint, eslint, prettier, tsc,
ls, find, grep, curl, wget
Commands already using lean-ctx pass through unchanged.
Directory listing:
# ls -la src/ (22 lines, ~239 tokens) # lean-ctx -c "ls -la src/" (8 lines, ~46 tokens)
total 96 core/
drwxr-xr-x 4 user staff 128 ... tools/
drwxr-xr-x 11 user staff 352 ... cli.rs 9.0K
-rw-r--r-- 1 user staff 9182 ... main.rs 4.0K
-rw-r--r-- 1 user staff 4096 ... server.rs 11.9K
... shell.rs 5.2K
4 files, 2 dirs
[lean-ctx: 239→46 tok, -81%]
File reading (map mode):
# Full read (284 lines, ~2078 tokens) # lean-ctx read stats.rs -m map (~30 tokens)
use serde::{Deserialize, Serialize}; stats.rs [284L]
use std::collections::HashMap; deps: serde::
use std::path::PathBuf; exports: StatsStore, load, save, record, format_gain
API:
#[derive(Serialize, Deserialize)] cl ⊛ StatsStore
pub struct StatsStore { fn ⊛ load() → StatsStore
pub total_commands: u64, fn ⊛ save(store:&StatsStore)
pub total_input_tokens: u64, fn ⊛ record(command:s, input_tokens:n, output_tokens:n)
... fn ⊛ format_gain() → String
(284 more lines) [2078 tok saved (100%)]
curl (JSON):
# curl -s httpbin.org/json (428 bytes) # lean-ctx -c "curl -s httpbin.org/json"
{ JSON (428 bytes):
"slideshow": { {
"author": "Yours Truly", slideshow: {4K}
"date": "date of publication", }
"slides": [ [lean-ctx: 127→14 tok, -89%]
{
"title": "Wake up to WonderWidgets!",
"type": "all"
},
...
Visual terminal dashboard with ANSI colors, Unicode block bars, sparklines, and USD estimates (cost uses $2.50 per 1M tokens consistently with the web dashboard and MCP metrics):
$ lean-ctx gain
◆ lean-ctx Token Savings Dashboard
────────────────────────────────────────────────────────
1.7M 76.8% 520 $4.25
tokens saved compression commands USD saved
Since 2026-03-23 (2 days) ▁█
Top Commands
────────────────────────────────────────────────────────
curl 48x ████████████████████ 728.1K 97%
git commit 34x ██████████▎ 375.2K 50%
git rm 7x ████████▌ 313.4K 100%
git show 4x ████▊ 173.8K 99%
ctx_read 103x █▌ 59.1K 38%
cat 15x ▊ 29.3K 92%
npm run 13x ▏ 7.0K 90%
... +33 more commands
Recent Days
────────────────────────────────────────────────────────
03-23 101 cmds 9.4K saved 46.0%
03-24 419 cmds 1.7M saved 77.0%
────────────────────────────────────────────────────────
lean-ctx v1.8.2 | leanctx.com | lean-ctx dashboard
30-day savings chart with lean-ctx gain --graph:
◆ lean-ctx Token Savings Graph (last 30 days)
──────────────────────────────────────────────────────────
peak: 1.7M
03-23 │ ▏ 9.4K 46%
03-24 │ ████████████████████████████████████ 1.7M 77%
──────────────────────────────────────────────────────────
▁█ 1.7M saved across 520 commands
Daily breakdown table with lean-ctx gain --daily:
◆ lean-ctx Daily Breakdown
┌────────────────────────────────────────────────────────────────┐
│ Date Cmds Input Saved Rate USD │
├────────────────────────────────────────────────────────────────┤
│ 2026-03-23 101 20.5K 9.4K 46.0% $0.02 │
│ 2026-03-24 419 2.2M 1.7M 77.0% $4.22 │
├────────────────────────────────────────────────────────────────┤
│ TOTAL 520 2.2M 1.7M 76.8% $4.25 │
└────────────────────────────────────────────────────────────────┘
Trend: ▁█
When configured as an MCP server, lean-ctx provides 10 tools that replace or augment your editor's built-in tools:
| Tool | Replaces | Savings |
|---|---|---|
ctx_read |
File reads — modes: full, map, signatures, diff, aggressive, entropy, lines:N-M (comma-separated ranges). Supports fresh=true to bypass cache. |
74-99% |
ctx_multi_read |
Multiple file reads in one round trip (same modes per file) | 74-99% |
ctx_tree |
Directory listings (ls, find, Glob) | 34-60% |
ctx_shell |
Shell commands | 60-90% |
ctx_search |
Code search (Grep) | 50-80% |
ctx_compress |
Context checkpoint for long conversations | 90-99% |
ctx_benchmark |
Compare all compression strategies with tiktoken counts | — |
ctx_metrics |
Session statistics with USD cost estimates ($2.50/1M) | — |
ctx_analyze |
Shannon entropy analysis + mode recommendation | — |
ctx_cache |
Cache management: status, clear, invalidate. Use clear when spawned as a subagent. |
— |
| Mode | When to use | Token cost |
|---|---|---|
full |
Files you will edit (cached re-reads = ~13 tokens). Set fresh=true to force re-read. |
100% first read, ~0% cached |
map |
Understanding a file without reading it — dependency graph + exports + API | ~5-15% |
signatures |
API surface with more detail than map | ~10-20% |
diff |
Re-reading files that changed | only changed lines |
aggressive |
Large files with boilerplate | ~30-50% |
entropy |
Files with repetitive patterns (Shannon + Jaccard filtering) | ~20-40% |
lines:N-M |
Only specific line ranges (e.g. lines:10-50,80-90) |
proportional to selected lines |
The session cache auto-clears after 5 minutes of inactivity (configurable via LEAN_CTX_CACHE_TTL). This handles new chats, context compaction, and session resets server-side without relying on the LLM.
For explicit control:
- Use
ctx_readwithfresh=trueto bypass cache and get full content - Call
ctx_cache(action: "clear")to reset the entire cache - Call
ctx_cache(action: "invalidate", path: "...")to reset a single file
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}Add .github/copilot/mcp.json to your project:
{
"servers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}claude mcp add lean-ctx lean-ctxAdd to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}Add to ~/.codex/config.toml:
[mcp_servers.lean-ctx]
command = "lean-ctx"
args = []Or via CLI: codex mcp add lean-ctx
Add to ~/.gemini/antigravity/mcp_config.json:
{
"mcpServers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}Add to ~/.config/opencode/opencode.json (global) or opencode.json (project):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"lean-ctx": {
"type": "local",
"command": ["lean-ctx"],
"enabled": true
}
}
}OpenClaw uses a skills-based system instead of MCP. LeanCTX integrates via the shell hook — all commands OpenClaw runs through its exec tool are automatically compressed when the lean-ctx aliases are active.
# 1. Install shell aliases (if not done already)
lean-ctx init --global
source ~/.zshrc
# 2. (Optional) Install the LeanCTX skill for deeper integration
mkdir -p ~/.openclaw/skills/lean-ctx
cp skills/lean-ctx/SKILL.md ~/.openclaw/skills/lean-ctx/The skill teaches OpenClaw to prefer lean-ctx -c <command> for shell operations, use compressed file reads, and leverage the dashboard for analytics.
Add a lean-ctx terminal profile for automatic shell hook in Cursor:
{
"terminal.integrated.profiles.osx": {
"lean-ctx": {
"path": "lean-ctx",
"args": ["shell"],
"icon": "terminal"
}
}
}For maximum token savings, add a Cursor rule to your project:
cp examples/lean-ctx.mdc .cursor/rules/lean-ctx.mdcThis instructs the LLM to prefer lean-ctx tools and use compact output patterns (CRP v2).
lean-ctx init --globalThis adds 23 aliases to your shell profile:
- macOS/Linux:
.zshrc/.bashrc/config.fish - Windows: PowerShell profile (
Documents\PowerShell\Microsoft.PowerShell_profile.ps1)
Or add manually to your shell profile:
Bash/Zsh:
alias git='lean-ctx -c git'
alias npm='lean-ctx -c npm'
alias cargo='lean-ctx -c cargo'
alias docker='lean-ctx -c docker'
alias kubectl='lean-ctx -c kubectl'
# ... and 18 more (run lean-ctx init --global for all)PowerShell:
function git { & lean-ctx -c "git $($args -join ' ')" }
function npm { & lean-ctx -c "npm $($args -join ' ')" }
function cargo { & lean-ctx -c "cargo $($args -join ' ')" }
# ... and 14 more (run lean-ctx init --global for all)Or use the interactive shell:
lean-ctx shelllean-ctx tracks all compressions (both MCP tools and shell hook) in ~/.lean-ctx/stats.json:
- Per-command breakdown with token counts and USD estimates ($2.50/1M tokens, aligned with MCP)
- Color-coded compression bars with Unicode block characters
- Sparkline trends showing savings trajectory
- Daily statistics (last 90 days) with rate coloring
- Total lifetime savings with 4 KPI metrics
View in the terminal with the visual dashboard:
lean-ctx gain # Visual dashboard (colors, bars, sparklines)
lean-ctx gain --graph # 30-day savings chart
lean-ctx gain --daily # Bordered day-by-day table with USD
lean-ctx gain --json # Raw JSON exportOr open the web dashboard:
lean-ctx dashboardOpens http://localhost:3333 with:
- 5 KPI cards (tokens saved, savings rate, commands, days active, cost saved)
- 5 interactive charts (cumulative savings, daily rate, activity, top commands, distribution)
- MCP vs Shell Hook breakdown
- Command table with compression bars
- Daily history
| Feature | RTK | lean-ctx |
|---|---|---|
| Architecture | Shell hook only | Hybrid: Shell hook + MCP server |
| Language | Rust | Rust |
| CLI compression | ~50 commands | 75+ patterns (git, npm, cargo, docker, gh, kubectl, pip, ruff, eslint, prettier, tsc, go, terraform, make, maven, gradle, dotnet, flutter, dart, poetry, uv, playwright, rubocop, bundle, vitest, curl, wget, JSON, logs...) |
| File reading | rtk read (signatures mode) |
Modes: full (cached), map, signatures, diff, aggressive, entropy, lines:N-M |
| File caching | ✗ | ✓ MD5 session cache (re-reads = ~13 tokens) |
| Signature engine | Line-by-line regex | tree-sitter AST (14 languages) |
| Dependency maps | ✗ | ✓ import/export extraction (14 languages via tree-sitter) |
| Context checkpoints | ✗ | ✓ ctx_compress for long conversations |
| Token counting | Estimated | tiktoken-exact (o200k_base) |
| Entropy analysis | ✗ | ✓ Shannon entropy + Jaccard similarity |
| Cost tracking | ✗ | ✓ USD estimates per session ($2.50/1M) |
| Token Dense Dialect | ✗ | ✓ TDD mode: symbol shorthand (λ, §, ∂) + identifier mapping (8-25% extra) |
| Thinking reduction | ✗ | ✓ CRP v2 (30-60% fewer thinking tokens via Cursor Rules) |
| Stats & Graphs | ✓ rtk gain (SQLite + ASCII graph) |
✓ Visual terminal dashboard (ANSI colors, Unicode bars, sparklines, USD) + --graph + --daily + --json + web dashboard |
| Auto-setup | ✓ rtk init |
✓ lean-ctx init |
| Editors | Claude Code, OpenCode, Gemini CLI | All MCP editors (Cursor, Copilot, Claude Code, Windsurf, Codex, Antigravity, OpenCode) + shell hook (OpenClaw, any terminal) |
| Config file | TOML | ✓ TOML (~/.lean-ctx/config.toml) |
| History analysis | ✗ | ✓ lean-ctx discover — find uncompressed commands |
| Homebrew | ✓ | ✓ brew tap yvgude/lean-ctx && brew install lean-ctx |
| Adoption tracking | ✗ | ✓ lean-ctx session — adoption % |
Key difference: RTK compresses CLI output only. lean-ctx compresses CLI output and file reads, search results, and project context through the MCP protocol — reaching up to 99% savings on cached re-reads and 60-90% on CLI output.
Since v1.5.0, lean-ctx uses tree-sitter for AST-based signature extraction (enabled by default). This replaces the previous regex-based extractor with accurate parsing of multi-line signatures, arrow functions, and nested definitions.
14 languages supported: TypeScript, JavaScript, Rust, Python, Go, Java, C, C++, Ruby, C#, Kotlin, Swift, PHP
| Capability | Regex (old) | tree-sitter (new) |
|---|---|---|
| Multi-line signatures | Missed | Fully parsed |
| Arrow functions | Missed | Fully parsed |
| Nested classes/methods | Heuristic | AST scope tracking |
| Languages | 4 | 14 |
Build without tree-sitter for a smaller binary (~5.7 MB vs ~17 MB):
cargo install lean-ctx --no-default-featuresmacOS/Linux:
# Remove shell aliases from your profile (.zshrc / .bashrc / config.fish)
# Remove binary
brew uninstall lean-ctx # if installed via Homebrew
cargo uninstall lean-ctx # if installed via cargo
# Remove stats and config
rm -rf ~/.lean-ctxWindows (PowerShell):
# Remove lean-ctx functions from your PowerShell profile
# notepad $PROFILE
cargo uninstall lean-ctx # if installed via cargo
# Remove stats and config
Remove-Item -Recurse -Force "$env:USERPROFILE\.lean-ctx"Contributions welcome! Please open an issue or PR on GitHub.
MIT License — see LICENSE for details.