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

# 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.17.0  |  leanctx.com  |  lean-ctx dashboard

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

~/.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
    }
  }
}