yvgude/lean ctx

  ██╗     ███████╗ █████╗ ███╗   ██╗     ██████╗████████╗██╗  ██╗
  ██║     ██╔════╝██╔══██╗████╗  ██║    ██╔════╝╚══██╔══╝╚██╗██╔╝
  ██║     █████╗  ███████║██╔██╗ ██║    ██║        ██║    ╚███╔╝ 
  ██║     ██╔══╝  ██╔══██║██║╚██╗██║    ██║        ██║    ██╔██╗ 
  ███████╗███████╗██║  ██║██║ ╚████║    ╚██████╗   ██║   ██╔╝ ██╗
  ╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝     ╚═════╝   ╚═╝   ╚═╝  ╚═╝
             The Intelligence Layer for AI Coding

lean-ctx reduces LLM token consumption by up to 99% through three complementary strategies in a single binary — making AI coding faster, cheaper, and more effective.

⚡ What It Does

  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) ─────┴──────────────┘

🎯 Token Savings — Real Numbers

Based on typical Cursor/Claude Code sessions with medium TypeScript/Rust projects. Cached re-reads cost ~13 tokens.

🚀 Get Started (60 seconds)

# 1. Install (pick one)
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. Setup (auto-configures shell + ALL detected editors)
lean-ctx setup

# 3. Verify
lean-ctx doctor

lean-ctx creates a backup of your shell config before modifying it (~/.zshrc.lean-ctx.bak).

🧠 Three Intelligence Protocols

CEP

Cognitive Efficiency Protocol

Adaptive LLM communication with compliance scoring (0-100), task complexity classification, quality scoring, auto-validation pipeline.

Measurable efficiency gains

CCP

Context Continuity Protocol

Cross-session memory that persists tasks, findings, decisions across chats. LITM-aware positioning for optimal attention placement.

-99.2% cold-start tokens

TDD

Token Dense Dialect

Symbol shorthand (λ § ∂ τ ε) and ROI-based identifier mapping for compact LLM communication.

8-25% extra savings

🛠 24 Intelligent Tools

Core

Intelligence

Memory & Multi-Agent

Analysis

📖 ctx_read Modes

🔌 Shell Hook Patterns (90+)

Pattern-based compression for 90+ commands across 34 categories:

After lean-ctx init --global, 23 commands are transparently compressed via shell aliases:

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

👀 Examples

# ls -la src/                               # lean-ctx -c "ls -la src/"
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%]

# 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 -s httpbin.org/json                   # 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!",
        ...

$ lean-ctx gain

  ◆ lean-ctx  Token Savings Dashboard
  ────────────────────────────────────────────────────────

   1.7M          76.8%         520          $33.71
   tokens saved   compression    commands       USD saved

  Cost Breakdown  (@ $2.50/M input, $10/M output)
  ────────────────────────────────────────────────────────
  Without lean-ctx    $44.75  ($5.79 input + $38.96 output)
  With lean-ctx       $11.04  ($1.76 input + $9.28 output)
  Saved               $33.71  ($4.03 input + $29.68 output)

  Top Commands
  ────────────────────────────────────────────────────────
  curl                48x  ████████████████████ 728.1K  97%
  git commit          34x  ██████████▎          375.2K  50%
  ctx_read           103x  █▌                    59.1K  38%
    ... +33 more commands

  lean-ctx v2.12.6  |  leanctx.com  |  lean-ctx dashboard

🔬 Scientific Compression Engine

Built on information theory and attention modeling (v2.6):

🌳 tree-sitter Signature Engine

AST-based signature extraction for 14 languages: TypeScript, JavaScript, Rust, Python, Go, Java, C, C++, Ruby, C#, Kotlin, Swift, PHP.

Build without tree-sitter for a smaller binary (~5.7 MB vs ~17 MB):

cargo install lean-ctx --no-default-features

📊 CLI Commands

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

lean-ctx read file.rs                         # Full content (structured header)
lean-ctx read file.rs -m map                  # Deps + API signatures (~10% tokens)
lean-ctx read file.rs -m signatures           # Function/class signatures only
lean-ctx read file.rs -m aggressive           # Syntax-stripped (~40% tokens)
lean-ctx read file.rs -m entropy              # Shannon entropy filtered (~30%)
lean-ctx read file.rs -m "lines:10-50,80-90"  # Specific line ranges
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

lean-ctx setup                 # One-command setup: shell + editors + verify
lean-ctx init --global         # Install 23 shell aliases
lean-ctx init --agent claude   # Claude Code hook
lean-ctx init --agent cursor   # Cursor hooks.json
lean-ctx init --agent gemini   # Gemini CLI hook
lean-ctx init --agent codex    # Codex AGENTS.md
lean-ctx init --agent windsurf # .windsurfrules
lean-ctx init --agent cline    # .clinerules
lean-ctx init --agent pi       # Pi Coding Agent extension
lean-ctx gain                  # Visual terminal dashboard
lean-ctx gain --live           # Live auto-updating dashboard
lean-ctx gain --graph          # ASCII chart (30 days)
lean-ctx gain --daily          # Day-by-day breakdown
lean-ctx gain --json           # Raw JSON export
lean-ctx dashboard             # Web dashboard (localhost:3333)
lean-ctx cheatsheet            # Quick reference
lean-ctx discover              # Find uncompressed commands
lean-ctx doctor                # Diagnostics
lean-ctx update                # Self-update
lean-ctx wrapped               # Shareable savings report
lean-ctx benchmark run         # Real project benchmark
lean-ctx benchmark report      # Markdown report

lctx                              # Auto-detect agent, current dir
lctx --agent claude               # Launch Claude Code with lean-ctx
lctx --agent cursor               # Configure Cursor
lctx --agent gemini               # Launch Gemini CLI
lctx /path/to/project "prompt"    # Project + prompt
lctx --scan-only                  # Build project graph only

⚙️ Editor Configuration

lean-ctx setup handles this automatically. Manual config below is only needed for edge cases.

~/.cursor/mcp.json:

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

.github/copilot/mcp.json:

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

claude mcp add lean-ctx lean-ctx

~/.codeium/windsurf/mcp_config.json:

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

If tools don't load, use the full path (e.g., /Users/you/.cargo/bin/lean-ctx). Windsurf spawns MCP servers with a minimal PATH.

~/.config/zed/settings.json:

{
  "context_servers": {
    "lean-ctx": {
      "source": "custom",
      "command": "lean-ctx",
      "args": [],
      "env": {}
    }
  }
}

~/.codex/config.toml:

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

~/.gemini/settings/mcp.json:

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

lean-ctx init --agent pi
# Or: pi install npm:pi-lean-ctx

Pi's bash, read, grep, find, and ls tools are automatically routed through lean-ctx. Supports 55+ file extensions with auto mode selection.

~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "lean-ctx": {
      "type": "local",
      "command": ["lean-ctx"],
      "enabled": true
    }
  }
}

🏆 lean-ctx vs RTK

🔐 Security

lean-ctx is local-only — zero network requests, zero telemetry. See SECURITY.md.

Note on VirusTotal: Rust binaries are frequently flagged by ML-based heuristic scanners. This is a known issue. Build from source with cargo install lean-ctx to verify.

🗑 Uninstall

lean-ctx init --global   # See what was added, then remove from shell profile
cargo uninstall lean-ctx # Remove binary
rm -rf ~/.lean-ctx       # Remove stats + config

🤝 Contributing

Contributions welcome! Open an issue or PR on GitHub.

📄 License

MIT — see LICENSE.