# lean-ctx **Context Engineering for AI Agents with CCP + TDD. Shell Hook + MCP Server. 81 MCP tools, 10 read modes, 95+ shell patterns, cross-session memory (CCP), LITM-aware positioning, tree-sitter AST for 26 languages. Single Rust binary.** [![CI](https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml/badge.svg)](https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml) [![Security Check](https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml/badge.svg)](https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml) [![Crates.io](https://img.shields.io/crates/v/lean-ctx)](https://crates.io/crates/lean-ctx) [![Downloads](https://img.shields.io/crates/d/lean-ctx)](https://crates.io/crates/lean-ctx) [![AUR](https://img.shields.io/aur/version/lean-ctx)](https://aur.archlinux.org/packages/lean-ctx) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/pTHkG9Hew9) [Website](https://leanctx.com) · [Install](#installation) · [Quick Start](#quick-start) · [CLI Reference](#cli-commands) · [MCP Tools](#79-mcp-tools) · [Changelog](CHANGELOG.md) · [vs RTK](#lean-ctx-vs-rtk) · [Discord](https://discord.gg/pTHkG9Hew9) --- lean-ctx reduces LLM token consumption by **up to 99%** through two complementary strategies in a single binary: 1. **Shell Hook** — Transparently compresses CLI output (95+ patterns) before it reaches the LLM. Works without LLM cooperation. 2. **MCP Server** — 80 tools for cached file reads, adaptive mode selection, incremental deltas, dependency maps, intent detection, cross-file dedup, project graph, cross-session memory (CCP), multi-agent coordination, semantic caching, and session metrics. Works with Cursor, GitHub Copilot, Claude Code, CodeBuddy, Windsurf, OpenAI Codex, Google Antigravity, OpenCode, and any MCP-compatible editor. 3. **AI Tool Hooks** — One-command integration for Claude Code, CodeBuddy, Cursor, Gemini CLI, Codex, Crush, Windsurf, and Cline via `lean-ctx init --agent `. ## 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) ```bash brew tap yvgude/lean-ctx brew install lean-ctx ``` ### Arch Linux (AUR) ```bash yay -S lean-ctx # builds from source (crates.io) # or yay -S lean-ctx-bin # pre-built binary (GitHub Releases) ``` ### Cargo ```bash cargo install lean-ctx ``` ### Build from Source ```bash 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: > ```bash > echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc > ``` Contributors iterating on the Rust engine (~700 dependencies) can opt into a faster local build (lld linker + sccache, Linux): `./scripts/setup-fast-build.sh`. One-time setup per machine; measured ~30% faster clean builds and ~2x faster incremental rebuilds. ### Verify Installation ```bash lean-ctx --version # Should show "lean-ctx 3.6.10" 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 ```bash # 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 ```bash 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 ```bash 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 ``` ### Context Packages ```bash lean-ctx pack create --name my-pkg # Bundle Knowledge + Graph + Session + Gotchas lean-ctx pack list # List installed packages lean-ctx pack info my-pkg # Detailed view (stats, integrity, provenance) lean-ctx pack export my-pkg -o my.ctxpkg # Export to portable .ctxpkg file lean-ctx pack import my.ctxpkg --apply # Import and apply to current project lean-ctx pack install my-pkg # Apply package (merge knowledge, import graph) lean-ctx pack auto-load my-pkg # Auto-load on ctx_overview session start lean-ctx pack remove my-pkg # Remove from local registry lean-ctx pack --pr # PR context pack (unchanged) ``` ### Setup & Analytics ```bash 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 codebuddy # Install CodeBuddy 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 + compatible hooks lean-ctx init --agent windsurf # Install .windsurfrules lean-ctx init --agent cline # Install .clinerules lean-ctx init --agent crush # Install Crush MCP config 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 # Show session details lean-ctx sessions delete # Delete one session 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 ```bash lean-ctx # Start MCP server (stdio) — used by editors ``` ## Shell Hook Patterns (95+) The shell hook applies pattern-based compression for 95+ 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, 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% | | **AWS** (7) | s3, ec2, lambda, cloudformation, ecs, logs, sts | -60-80% | | **Databases** (2) | psql, mysql/mariadb | -50-80% | | **Prisma** (6) | generate, migrate, db push/pull, format, validate | -70-85% | | **Helm** (5) | list, install, upgrade, status, template | -60-80% | | **Bun** (3) | test, install, build | -60-85% | | **Deno** (5) | test, lint, check, fmt, task | -60-85% | | **Swift** (3) | test, build, package resolve | -60-80% | | **Zig** (2) | test, build | -60-80% | | **CMake** (3) | configure, build, ctest | -60-80% | | **Ansible** (2) | playbook recap, task summary | -60-80% | | **Composer** (3) | install, update, outdated | -60-80% | | **Mix** (5) | test, deps, compile, format, credo/dialyzer | -60-80% | | **Bazel** (3) | test, build, query | -60-80% | | **systemd** (2) | systemctl, journalctl | -50-80% | | **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% ctx_read 103x █▌ 59.1K 38% cat 15x ▊ 29.3K 92% ... +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 v3.6.10 | leanctx.com | lean-ctx dashboard ``` ## 81+ MCP Tools When configured as an MCP server, lean-ctx provides 80 tools that replace or augment your editor's built-in tools: ### Core Tools | Tool | Purpose | Savings | |---|---|---| | `ctx_read` | File reads — 10 modes incl. `lines:N-M`. Supports `fresh=true` to bypass cache. | 74-99% | | `ctx_multi_read` | Multiple file reads in one round trip | 74-99% | | `ctx_tree` | Directory listings (ls, find, Glob) | 34-60% | | `ctx_shell` | Shell commands with 95+ compression patterns | 60-90% | | `ctx_search` | Code search (Grep) | 50-80% | | `ctx_compress` | Context checkpoint for long conversations | 90-99% | ### Intelligence Tools | Tool | Purpose | |---|---| | `ctx_smart_read` | Adaptive mode selection — automatically picks full/map/signatures/diff based on file type, size, and cache state | | `ctx_delta` | Incremental file updates — only sends changed hunks via Myers diff | | `ctx_dedup` | Cross-file deduplication — finds shared imports and boilerplate across cached files | | `ctx_fill` | Priority-based context filling — maximizes information within a token budget | | `ctx_intent` | Semantic intent detection — classifies queries and auto-loads relevant files | | `ctx_response` | Response compression — removes filler content, applies TDD shortcuts | | `ctx_context` | Multi-turn session overview — tracks what the LLM already knows | | `ctx_graph` | Project intelligence graph — dependency analysis and related file discovery | | `ctx_discover` | Shell history analysis — finds missed compression opportunities | | `ctx_edit` | Search-and-replace file editing — works without native Read/Edit tools | | `ctx_overview` | Task-relevant project map — use at session start | | `ctx_preload` | Proactive context loader — caches task-relevant files, returns compact summary | | `ctx_semantic_search` | BM25 code search by meaning — finds symbols and patterns across the project | ### Memory & Multi-Agent Tools | Tool | Purpose | |---|---| | `ctx_session` | Cross-session memory — persist task, findings, decisions, files across chats and context compactions | | `ctx_knowledge` | Persistent project knowledge — remember, recall, export, import, remove, search, timeline, relations | | `ctx_agent` | Multi-agent coordination — register, post/read scratchpad, handoff tasks, sync status | | `ctx_share` | Multi-agent context sharing — push/pull cached file contexts between agents | | `ctx_gain` | Savings report card — wrapped report, summary, delta (action=wrapped for "Spotify Wrapped" style) | ### Analysis Tools | Tool | Purpose | |---|---| | `ctx_benchmark` | Single-file or project-wide benchmark with preservation scores | | `ctx_metrics` | Session statistics with USD cost estimates ($2.50/1M) | | `ctx_analyze` | Shannon entropy analysis + mode recommendation | | `ctx_compare` | Preview compression — original vs the bytes lean-ctx would emit, with token counts + line diff (read-only) | | `ctx_cache` | Cache management: status, clear, invalidate | ### 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 ### Context Continuity Protocol (CCP) New in v2.0.0: CCP provides cross-session memory that persists across chats, context compactions, and IDE restarts. The session state captures your current task, findings, decisions, and files touched — automatically loaded into every new conversation. **How it works:** - Session state is stored as JSON in `~/.lean-ctx/sessions/` - Automatically loaded into server instructions on startup - Uses LITM-aware positioning: critical context placed at the beginning and end of the LLM's context window (where attention is highest), avoiding the "Lost in the Middle" degradation zone - Incrementally updated after each tool call - Auto-saved during checkpoints and idle cache expiry **CLI commands:** ```bash lean-ctx sessions list # List all sessions lean-ctx sessions show # Show session details lean-ctx sessions delete # Delete one session lean-ctx sessions cleanup # Remove old sessions lean-ctx wrapped # Shareable savings report lean-ctx wrapped --week # Weekly report lean-ctx benchmark run # Real project benchmark lean-ctx benchmark report # Shareable Markdown report ``` **MCP usage:** ```json {"tool": "ctx_session", "arguments": {"action": "status"}} {"tool": "ctx_session", "arguments": {"action": "task", "value": "Implement auth module"}} {"tool": "ctx_session", "arguments": {"action": "finding", "value": "Auth uses JWT with RS256"}} {"tool": "ctx_session", "arguments": {"action": "decision", "value": "Use middleware pattern for auth"}} {"tool": "ctx_gain", "arguments": {"action": "wrapped"}} ``` ## Editor Configuration ### Cursor Add to `~/.cursor/mcp.json`: ```json { "mcpServers": { "lean-ctx": { "command": "lean-ctx" } } } ``` ### GitHub Copilot Add `.github/mcp.json` to your project (Copilot CLI): ```json { "mcpServers": { "lean-ctx": { "command": "lean-ctx" } } } ``` Or `.vscode/mcp.json` for VS Code Copilot: ```json { "servers": { "lean-ctx": { "type": "stdio", "command": "lean-ctx" } } } ``` ### Claude Code ```bash claude mcp add lean-ctx lean-ctx ``` ### Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "lean-ctx": { "command": "lean-ctx" } } } ``` > **Troubleshooting:** If Windsurf detects the server but tools don't load, use the **full path** to the binary (e.g., `/Users/you/.cargo/bin/lean-ctx` or `/usr/local/bin/lean-ctx`). Windsurf spawns MCP servers with a minimal PATH that may not include `~/.cargo/bin`. Find your path with `which lean-ctx`. ### OpenAI Codex Add to `~/.codex/config.toml`: ```toml [mcp_servers.lean-ctx] command = "lean-ctx" args = [] ``` Or via CLI: `codex mcp add lean-ctx` Then run: ```bash lean-ctx init --agent codex ``` This installs: - `~/.codex/AGENTS.md` + `~/.codex/LEAN-CTX.md` - a `PreToolUse` hook that transparently rewrites rewritable Bash commands to `lean-ctx -c ""` (allowed + `updatedInput`), so shell output is compressed with zero agent effort - a `SessionStart` hook that teaches Codex the raw escape hatch — `lean-ctx raw ""` for the full, exact output — so it never re-reads a compressed view in small chunks ### Google Antigravity Add to `~/.gemini/antigravity/mcp_config.json`: ```json { "mcpServers": { "lean-ctx": { "command": "lean-ctx" } } } ``` ### OpenCode Add to `~/.config/opencode/opencode.json` (global) or `opencode.json` (project): ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "lean-ctx": { "type": "local", "command": ["lean-ctx"], "enabled": true } } } ``` ### OpenClaw OpenClaw supports MCP servers natively. Run the init command to configure lean-ctx as an MCP server and install skills: ```bash lean-ctx init --agent openclaw ``` This writes the MCP server entry to `~/.openclaw/openclaw.json` under `mcp.servers`, installs global rules, and copies the LeanCTX skill to `~/.openclaw/skills/lean-ctx/`. Restart OpenClaw to activate. You can verify the configuration with `openclaw mcp list`. ### Cursor Terminal Profile Add a lean-ctx terminal profile for automatic shell hook in Cursor: ```json { "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: ```bash cp rust/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 ```bash lean-ctx init --global ``` This adds 23 aliases (git, npm, pnpm, yarn, cargo, docker, kubectl, gh, pip, ruff, go, golangci-lint, eslint, prettier, tsc, ls, find, grep, curl, wget, and more) to your `.zshrc` / `.bashrc` / `config.fish`. Or add manually to your shell profile: ```bash alias git='lean-ctx -c git' alias npm='lean-ctx -c npm' alias pnpm='lean-ctx -c pnpm' alias cargo='lean-ctx -c cargo' alias docker='lean-ctx -c docker' alias kubectl='lean-ctx -c kubectl' alias gh='lean-ctx -c gh' alias pip='lean-ctx -c pip' alias curl='lean-ctx -c curl' # ... and 14 more (run lean-ctx init --global for all) ``` Or use the interactive shell: ```bash lean-ctx shell ``` ### LSP Integration (Optional) `ctx_refactor` provides LSP-powered code intelligence (rename, references, go-to-definition, find-implementations). It requires an external language server to be installed — this is **optional** and not needed for core functionality. **Supported language servers:** | Language | Binary | Install | |---|---|---| | Rust | `rust-analyzer` | `rustup component add rust-analyzer` | | TypeScript/JS | `typescript-language-server` | `npm i -g typescript-language-server typescript` | | Python | `pylsp` | `pip install python-lsp-server` | | Go | `gopls` | `go install golang.org/x/tools/gopls@latest` | **Check availability:** ```bash lean-ctx doctor # Shows LSP server status in a dedicated section ``` **Custom paths** (in `~/.lean-ctx/config.toml`): ```toml [lsp] rust = "/opt/custom/rust-analyzer" python = "~/.venvs/main/bin/pylsp" ``` Without language servers, `ctx_search`, `ctx_symbol`, `ctx_graph`, and `ctx_callgraph` still provide powerful code navigation — LSP adds semantic precision for complex refactorings. ## 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**: ```bash 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: ```bash 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 | **95+ 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, aws, psql, mysql, prisma, helm, bun, deno, swift, zig, cmake, ansible, composer, mix, bazel, systemd, 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 (26 languages)** | | **Dependency maps** | ✗ | ✓ import/export extraction (26 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 % | | **Cross-session memory** | ✗ | ✓ CCP — persists task, findings, decisions across chats | | **LITM-aware positioning** | ✗ | ✓ Attention-optimal context placement (primacy/recency) | | **Savings reports** | ✗ | ✓ `lean-ctx wrapped` — shareable savings summary | | **Real project benchmarks** | ✗ | ✓ `lean-ctx benchmark run` — scans project files, measures tokens/latency/quality | **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. With CCP (v2.0.0), lean-ctx additionally eliminates cold-start overhead by persisting session state across conversations. ## tree-sitter Signature Engine Since v1.5.0, lean-ctx uses [tree-sitter](https://tree-sitter.github.io/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. **26 languages supported**: TypeScript, JavaScript, Rust, Python, Go, Java, C, C++, Ruby, C#, Kotlin, Swift, PHP, Bash, Dart, Scala, Elixir, Zig, GDScript, Lua, Luau, OCaml, Haskell, Julia, Solidity, Nix — plus signature extraction from embedded Vue/Svelte `