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

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/

Add ~/.local/bin to your PATH if needed:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc

Verify Installation

lean-ctx --version   # Should show "lean-ctx 2.1.1"
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:

1. Smart Filtering — Removes noise (progress bars, ANSI codes, whitespace, boilerplate)
2. Grouping — Aggregates similar items (files by directory, errors by type)
3. Truncation — Keeps relevant context, cuts redundancy
4. 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 (.zshrc/.bashrc/.config/fish)
lean-ctx init --agent claude   # Install Claude Code PreToolUse hook
lean-ctx init --agent cursor   # Install Cursor hooks.json
lean-ctx init --agent gemini   # Install Gemini CLI BeforeTool hook
lean-ctx init --agent codex    # Install Codex AGENTS.md
lean-ctx init --agent windsurf # Install .windsurfrules
lean-ctx init --agent cline    # Install .clinerules
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 wrapped               # Shareable savings report (CCP)
lean-ctx wrapped --week        # Weekly savings report
lean-ctx sessions list         # List CCP sessions
lean-ctx sessions show <id>    # Show session details
lean-ctx sessions cleanup      # Remove old sessions
lean-ctx benchmark run         # Real project benchmark (terminal)
lean-ctx benchmark run --json  # Machine-readable JSON output
lean-ctx benchmark report      # Shareable Markdown report
lean-ctx --version             # Show version
lean-ctx --help                # Full help

MCP Server

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

Shell Hook Patterns (90+)

The shell hook applies pattern-based compression for 90+ commands across 34 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, rol