lean-ctx

Hybrid Context Optimizer — Shell Hook + MCP Server in a single Rust binary.

Reduces LLM token consumption by 89-99%. Zero runtime dependencies.

Architecture

lean-ctx runs as both:

• Shell Hook — Transparently compresses CLI output (git, npm, cargo, docker, tsc, grep, find, ls, curl) before it reaches the LLM. Works without LLM cooperation.
• MCP Server — Provides 8 advanced tools for cached file reads, dependency maps, entropy analysis, and more. Works with any MCP-compatible editor.

Install

Build from source (requires Rust toolchain):

git clone https://gitlab.pounce.ch/root/lean-ctx.git
cd lean-ctx/rust
cargo build --release
cp target/release/lean-ctx ~/.local/bin/   # or /usr/local/bin

Make sure the install directory is in your PATH.

Configure

MCP Server (Cursor, Claude Code, Copilot, Windsurf)

Cursor — ~/.cursor/mcp.json:

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

Claude Code:

claude mcp add lean-ctx lean-ctx

GitHub Copilot — .github/copilot/mcp.json:

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

Windsurf — ~/.codeium/windsurf/mcp_config.json:

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

Shell Hook (Transparent CLI Compression)

Automatic setup:

lean-ctx init --global

This adds aliases for git, npm, cargo, docker, ls, find, grep, curl to your .zshrc / .bashrc / config.fish.

Or add manually to your shell profile:

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 ls='lean-ctx -c ls'
alias find='lean-ctx -c find'
alias grep='lean-ctx -c grep'
alias curl='lean-ctx -c curl'

Or use the interactive shell:

lean-ctx shell

Cursor terminal profile — add to VS Code settings:

{
  "terminal.integrated.profiles.osx": {
    "lean-ctx": {
      "path": "lean-ctx",
      "args": ["shell"],
      "icon": "terminal"
    }
  }
}

Cursor Rule

Add .cursor/rules/lean-ctx.mdc to your project for maximum token savings. Example included in examples/lean-ctx.mdc.

CLI Commands

8 MCP Tools

ctx_read Modes

How it works

MCP Server Mode

1. Session Cache: File reads are hashed (MD5) and cached. Re-reads return F1=auth.ts [cached 2t 151L ∅] (~13 tokens) instead of the full file.
2. Dependency Maps: ctx_read --mode map extracts imports, exports, and API signatures — understand a file at ~10% token cost.
3. Structured Headers: Every response includes F1=path [NL +] deps:[...] exports:[...] for instant context.
4. Signature Extraction: Function/class/type signatures for TS/JS, Rust, Python, Go.
5. Entropy Filtering: Shannon entropy removes low-information lines; Jaccard similarity deduplicates patterns.
6. CLI Compression: Pattern-based compression for git, npm, cargo, docker, tsc, grep, find, ls, curl, test runners.
7. Persistent Stats: All shell hook compressions are tracked in ~/.lean-ctx/stats.json. View with lean-ctx gain.

Shell Hook Mode

Transparently wraps shell commands and compresses output:

$ lean-ctx -c "ls -la src/"
core/
tools/
cli.rs  9.0K
main.rs  4.0K
server.rs  11.9K
shell.rs  5.2K
4 files, 2 dirs
[lean-ctx: 239→46 tok, -81%]

Token Savings Dashboard

$ lean-ctx gain
lean-ctx Token Savings
══════════════════════════════════════════════════
Total commands:  3
Input tokens:    452
Output tokens:   190
Tokens saved:    262 (58.0%)
Tracking since:  2026-03-23

By Command:
──────────────────────────────────────────────────
Command               Count      Saved   Avg%
ls                        1        177  74.1%
git status                1         85  39.9%
══════════════════════════════════════════════════

CRP v2 (Compact Response Protocol)

lean-ctx includes optimized system prompts (via Cursor Rules) that reduce LLM thinking tokens by 30-60% through structured task parsing and one-hypothesis reasoning.

vs RTK

License

MIT