lean-ctx

lean-ctx

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.

Token Savings (Typical Cursor/Claude Code Session)

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.

Installation

Homebrew (macOS / Linux)

brew tap yvgude/lean-ctx
brew install lean-ctx

Arch Linux (AUR)

yay -S lean-ctx # builds from source (crates.io)# or
yay -S lean-ctx-bin # pre-built binary (GitHub Releases)

Cargo

cargo install lean-ctx

Windows

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

Build from Source

git 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 PATH

Add ~/.local/bin to your PATH if needed (macOS/Linux):
echo'export PATH="$HOME/.local/bin:$PATH"'>>~/.zshrc # or ~/.bashrc

Verify Installation

lean-ctx --version # Should show "lean-ctx 1.8.2"
lean-ctx gain # Should show token savings stats

Token Dense Dialect (TDD)

lean-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)→s instead of fn pub async handle(&self, path: String) -> String
Long identifiers (>12 chars) are mapped to α1, α2... with a §MAP at 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 shorthand
compact — Moderate: skip filler words, use abbreviations
off — Standard output, no CRP instructions

Quick Start

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

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

How It Works

 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

CLI Commands

Shell Hook

lean-ctx -c "git status"# Execute + compress output
lean-ctx exec"cargo build"# Same as -c
lean-ctx shell # Interactive REPL with compression

File Operations

lean-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 summary

Setup & Analytics

lean-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 help

MCP Server

lean-ctx # Start MCP server (stdio) — used by editors

Shell Hook Patterns (75+)

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

23 Auto-Rewritten Aliases

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.

Examples

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: ▁█

10 MCP Tools

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

ctx_read Modes

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

Cache Safety

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_read with fresh=true to 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

Editor Configuration

Cursor

Add to ~/.cursor/mcp.json:

{
"mcpServers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}

GitHub Copilot

Add .github/copilot/mcp.json to your project:

{
"servers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}

Claude Code

claude mcp add lean-ctx lean-ctx

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
"mcpServers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.lean-ctx]
command = "lean-ctx"args = []

Or via CLI: codex mcp add lean-ctx

Google Antigravity

Add to ~/.gemini/antigravity/mcp_config.json:

{
"mcpServers": {
"lean-ctx": {
"command": "lean-ctx"
}
}
}

OpenCode

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

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.

Cursor Terminal Profile

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"
}
}
}

Cursor Rule (Optional)

For maximum token savings, add a Cursor rule to your project:

cp examples/lean-ctx.mdc .cursor/rules/lean-ctx.mdc

This instructs the LLM to prefer lean-ctx tools and use compact output patterns (CRP v2).

Configuration

Shell Hook Setup

lean-ctx init --global

This 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:

functiongit { & lean-ctx -c "git $($args-join'')" }
functionnpm { & lean-ctx -c "npm $($args-join'')" }
functioncargo { & lean-ctx -c "cargo $($args-join'')" }
# ... and 14 more (run lean-ctx init --global for all)

Or use the interactive shell:

lean-ctx shell

Persistent Stats & Web Dashboard

lean-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 export

Or open the web dashboard:

lean-ctx dashboard

Opens 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

lean-ctx vs RTK

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.

tree-sitter Signature Engine

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

Uninstall

macOS/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-ctx

Windows (PowerShell):

# Remove lean-ctx functions from your PowerShell profile# notepad $PROFILE
cargo uninstall lean-ctx # if installed via cargo# Remove stats and configRemove-Item-Recurse -Force "$env:USERPROFILE\.lean-ctx"

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

License

MIT License — see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
rust		rust
skills/lean-ctx		skills/lean-ctx
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CLAUDE_CODE_SETUP.md		CLAUDE_CODE_SETUP.md
README.md		README.md
VISION.md		VISION.md

Latest commit

History

Folders and files

Repository files navigation

lean-ctx

Token Savings (Typical Cursor/Claude Code Session)

Installation

Homebrew (macOS / Linux)

Arch Linux (AUR)

Cargo

Windows

Build from Source

Verify Installation

Token Dense Dialect (TDD)

Quick Start

How It Works

CLI Commands

Shell Hook

File Operations

Setup & Analytics

MCP Server

Shell Hook Patterns (75+)

23 Auto-Rewritten Aliases

Examples

10 MCP Tools

ctx_read Modes

Cache Safety

Editor Configuration

Cursor

GitHub Copilot

Claude Code

Windsurf

OpenAI Codex

Google Antigravity

OpenCode

OpenClaw

Cursor Terminal Profile

Cursor Rule (Optional)

Configuration

Shell Hook Setup

Persistent Stats & Web Dashboard

lean-ctx vs RTK

tree-sitter Signature Engine

Uninstall

Contributing

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages