Getting Started

Step 1: Install the Binary

Universal Installer (any platform)

The fastest way to install LeanCTX without any prerequisites:

curl -fsSL https://leanctx.com/install.sh | sh

The install script detects your OS and architecture, downloads the correct binary, and places it in ~/.local/bin (configurable via LEAN_CTX_INSTALL_DIR). It works on macOS, Linux, and WSL.

If you prefer to review the script before running it:

curl -fsSL https://leanctx.com/install.sh -o install.sh
chmod +x install.sh
./install.sh --download    # pre-built binary (no Rust)
./install.sh               # build from source (requires Rust)

npm (Node.js)

Install the pre-built binary via npm - no Rust toolchain required:

npm install -g lean-ctx-bin

This downloads the correct binary for your platform during postinstall with SHA256 verification. Works on macOS (Intel + Apple Silicon), Linux (x86_64), and Windows (x86_64).

macOS

Option A: Homebrew (recommended)

brew tap yvgude/lean-ctx
brew install lean-ctx

Homebrew handles updates and PATH automatically.

Option B: Cargo (build from source)

cargo install lean-ctx

If lean-ctx isn't found after install, add Cargo's bin directory to your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Option C: Manual binary download

1. Download the binary for your architecture from GitHub Releases:
   • lean-ctx-aarch64-apple-darwin.tar.gz (Apple Silicon / M1+)
   • lean-ctx-x86_64-apple-darwin.tar.gz (Intel)
2. Extract and move to PATH:

   tar xzf lean-ctx-aarch64-apple-darwin.tar.gz
   chmod +x lean-ctx
   sudo mv lean-ctx /usr/local/bin/

If macOS blocks the binary with a Gatekeeper warning, remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/lean-ctx

Linux

Option A: Homebrew

brew tap yvgude/lean-ctx && brew install lean-ctx

Option B: AUR (Arch Linux)

# Source build from crates.io
yay -S lean-ctx

# Or pre-built binary from GitHub
yay -S lean-ctx-bin

Works with any AUR helper: yay, paru, trizen, etc.

Option C: Cargo (build from source)

cargo install lean-ctx

Requires Rust toolchain. Install via rustup.rs if needed.

Option D: Manual binary download

1. Download lean-ctx-x86_64-unknown-linux-gnu.tar.gz from GitHub Releases
2. Extract and move to PATH:

   tar xzf lean-ctx-x86_64-unknown-linux-gnu.tar.gz
   chmod +x lean-ctx
   sudo mv lean-ctx /usr/local/bin/

Windows

Option A: Binary download (recommended)

1. Download lean-ctx-x86_64-pc-windows-msvc.zip from GitHub Releases
2. Extract the .zip file
3. Open the extracted folder - you'll see lean-ctx.exe
4. Move lean-ctx.exe to a folder in your PATH, for example:

   mkdir %USERPROFILE%\bin
   move lean-ctx.exe %USERPROFILE%\bin\

5. Add the folder to your PATH if it isn't already:
   • Open Settings → System → About → Advanced system settings
   • Click Environment Variables
   • Under User variables, select Path, click Edit, then New
   • Add the path to your bin folder (e.g. C:\Users\you\bin)
6. Open a new PowerShell or CMD window and verify:

   lean-ctx --version

Option B: Cargo (build from source)

1. Install Rust if not already installed
2. Build and install:

   cargo install lean-ctx

3. The binary is placed in %USERPROFILE%\.cargo\bin\ which is usually already in your PATH.

Option C: Build from source (clone & compile)

git clone https://github.com/yvgude/lean-ctx.git
cd lean-ctx\rust
cargo build --release
copy target\release\lean-ctx.exe %USERPROFILE%\bin\

WSL users: If you're running WSL, follow the Linux instructions instead.

Build from Source (any platform)

git clone https://github.com/yvgude/lean-ctx.git
cd lean-ctx/rust
cargo build --release

The binary is at target/release/lean-ctx (or lean-ctx.exe on Windows). Copy it to a directory in your PATH.

only if lean-ctx setup didn't work

Connect LeanCTX to your AI coding tool by adding it as an MCP server.

Cursor

1. Create or edit the MCP config file:

   # macOS / Linux:
   mkdir -p ~/.cursor
   nano ~/.cursor/mcp.json
   
   # Windows (PowerShell):
   mkdir -Force "$env:USERPROFILE\.cursor"
   notepad "$env:USERPROFILE\.cursor\mcp.json"

2. Paste this JSON:

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

3. Restart Cursor completely (Cmd+Q / Alt+F4, then reopen).
4. Verify: open the MCP panel in settings - LeanCTX should show as "connected".

Optional: install agent rules to make Cursor prefer LeanCTX tools:

lean-ctx init --agent cursor

Claude Code

Claude Code has built-in MCP support. No config file needed:

# Add lean-ctx as MCP server:
claude mcp add lean-ctx lean-ctx

# Install the CLAUDE.md instructions (makes Claude use lean-ctx tools):
lean-ctx init --agent claude

The init command registers the MCP server in <code>~/.claude.json</code>, maintains a compact instructions block in <code>~/.claude/CLAUDE.md</code>, and installs the Agent Skill to <code>~/.claude/skills/lean-ctx/</code>.

Claude Code: 2048-Character Limit

Claude Code truncates MCP server instructions to 2048 characters. This means LeanCTX's full instruction set (session management, compression protocols, tool preferences) gets cut off.

LeanCTX handles this automatically: lean-ctx init --agent claude maintains a managed block in ~/.claude/CLAUDE.md and installs an Agent Skill (~/.claude/skills/lean-ctx/) whose full documentation loads on demand. Claude Code loads these without any character cap.

# Automatic (recommended) - run during init:
lean-ctx init --agent claude

# This automatically:
# 1. Registers MCP server in ~/.claude.json
# 2. Maintains a compact instructions block in ~/.claude/CLAUDE.md
# 3. Installs Agent Skill to ~/.claude/skills/lean-ctx/ (full docs, loads on demand)

If you installed LeanCTX manually (without init), run lean-ctx init --agent claude to retroactively install the CLAUDE.md block + skill.

GitHub Copilot (VS Code)

Option A: Copilot CLI (.github/mcp.json)

1. Create .github/mcp.json in your project root:

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

2. Restart VS Code / Copilot CLI.

Option B: VS Code Copilot (.vscode/mcp.json)

1. Create .vscode/mcp.json in your project root:

   {
     "servers": {
       "lean-ctx": {
         "type": "stdio",
         "command": "lean-ctx"
       }
     }
   }

2. Restart VS Code.

Tip: lean-ctx init --agent copilot creates both files automatically.

Note: GitHub Copilot MCP support requires VS Code 1.99+ and the latest Copilot extension. Copilot CLI uses .github/mcp.json with the mcpServers key; VS Code Copilot uses .vscode/mcp.json with the servers key.

Per-project: These configs are per-project. Commit them to share with your team.

Windsurf

1. Open the MCP config file:

   # macOS:
   mkdir -p ~/.codeium/windsurf
   nano ~/.codeium/windsurf/mcp_config.json
   
   # Linux:
   mkdir -p ~/.codeium/windsurf
   nano ~/.codeium/windsurf/mcp_config.json
   
   # Windows:
   mkdir -Force "$env:USERPROFILE\.codeium\windsurf"
   notepad "$env:USERPROFILE\.codeium\windsurf\mcp_config.json"

2. Paste this JSON:

   {
     "mcpServers": {
       "lean-ctx": {
         "command": "/FULL/PATH/TO/lean-ctx"
       }
     }
   }

   Important: Windsurf requires the full absolute path to the binary. Example for Homebrew on macOS:

   {
     "mcpServers": {
       "lean-ctx": {
         "command": "/opt/homebrew/bin/lean-ctx"
       }
     }
   }

3. Restart Windsurf completely.
4. Check MCP connection in Windsurf settings.

Zed

1. Open Zed settings:

   # macOS / Linux:
   ~/.config/zed/settings.json
   
   # Windows:
   %APPDATA%\Zed\settings.json

2. Add the LeanCTX context server configuration:

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

   Note: Zed uses context_servers (not mcpServers) and requires source: "custom".

3. Save and restart Zed.
4. Verify: LeanCTX tools should appear in the assistant panel.

Tip: Zed auto-restarts MCP servers after saving settings.json. No additional rules injection needed — Zed receives tool preferences via the MCP server instructions.

OpenAI Codex CLI

1. Create or edit the Codex config file:

   # macOS / Linux:
   mkdir -p ~/.codex
   nano ~/.codex/config.toml
   
   # Windows:
   mkdir -Force "$env:USERPROFILE\.codex"
   notepad "$env:USERPROFILE\.codex\config.toml"

2. Add the MCP server entry:

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

3. Restart Codex CLI.

Alternative: use the Codex CLI built-in command:

codex mcp add lean-ctx

Install agent instructions for Codex:

lean-ctx init --agent codex

Gemini CLI

1. Create or edit the Gemini MCP config:

   # macOS / Linux:
   mkdir -p ~/.gemini
   nano ~/.gemini/settings.json
   
   # Windows (PowerShell):
   mkdir -Force "$env:USERPROFILE\.gemini"
   notepad "$env:USERPROFILE\.gemini\settings.json"

2. Add the MCP server configuration:

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

   Important: If Gemini can't find the binary, use the full path. Example for Homebrew on macOS:

   {
     "mcpServers": {
       "lean-ctx": {
         "command": "/opt/homebrew/bin/lean-ctx"
       }
     }
   }

3. Restart Gemini CLI.
4. Verify with a prompt that triggers tool use.

Known issue: Gemini CLI may not always invoke MCP tools consistently. If tools aren't triggered, try adding lean-ctx init --agent gemini to install a GEMINI.md with usage instructions.

Antigravity IDE

Antigravity IDE uses ~/.gemini/antigravity/mcp_config.json. Auto-detected by lean-ctx setup.

1. Create the config directory and file:

   # macOS / Linux:
   mkdir -p ~/.gemini/antigravity
   nano ~/.gemini/antigravity/mcp_config.json
   
   # Windows (PowerShell):
   mkdir -Force "$env:USERPROFILE\.gemini\antigravity"
   notepad "$env:USERPROFILE\.gemini\antigravity\mcp_config.json"

2. Add the MCP server entry:

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

   If lean-ctx is not in your PATH, use the full path (run which lean-ctx to find it).

3. Run lean-ctx init --agent antigravity to auto-configure.
4. Restart Antigravity IDE.

Antigravity CLI 2.0

Antigravity CLI uses a separate config at ~/.gemini/antigravity-cli/mcp_config.json.

1. Create the config directory and file:

   # macOS / Linux:
   mkdir -p ~/.gemini/antigravity-cli
   nano ~/.gemini/antigravity-cli/mcp_config.json
   
   # Windows (PowerShell):
   mkdir -Force "$env:USERPROFILE\.gemini\antigravity-cli"
   notepad "$env:USERPROFILE\.gemini\antigravity-cli\mcp_config.json"

2. Add the MCP server entry:

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

3. Run lean-ctx init --agent antigravity-cli to auto-configure.
4. Restart Antigravity CLI.

OpenCode

1. Create or edit the OpenCode config file:

   # macOS / Linux:
   mkdir -p ~/.config/opencode
   nano ~/.config/opencode/opencode.json

2. Add the MCP server configuration:

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

3. Restart OpenCode.

OpenClaw

OpenClaw supports MCP servers natively. Run one command to configure everything:

1. Run lean-ctx init --agent openclaw
2. Restart OpenClaw to activate.
3. Verify with openclaw mcp list.

This writes the MCP entry to ~/.openclaw/openclaw.json, installs rules, and copies the LeanCTX skill to ~/.openclaw/skills/lean-ctx/.

Pi

Pi has a dedicated LeanCTX plugin (pi-lean-ctx) that integrates automatically.

1. Make sure LeanCTX is installed:

   cargo install lean-ctx

2. Install the Pi plugin:

   pi install npm:pi-lean-ctx

   Or use LeanCTX's built-in command:

   lean-ctx init --agent pi

3. Restart Pi.
4. Verify: LeanCTX tools should appear in Pi's tool list.

Note: Pi's smart reads automatically use LeanCTX when the plugin is installed. No additional configuration needed.

AWS Kiro

AWS Kiro requires both an MCP config and a steering file to use LeanCTX tools instead of native equivalents.

1. Run lean-ctx setup - Kiro is auto-detected and both MCP config + steering file are created.
2. Or use the dedicated command (creates both files):

   lean-ctx init --agent kiro

3. This creates two files:
   • ~/.kiro/settings/mcp.json - MCP server connection
   • .kiro/steering/lean-ctx.md - Steering file that tells Kiro to prefer mcp_lean_ctx_ctx_read over readFile, etc.
4. Restart Kiro to activate.

Important: The steering file (.kiro/steering/lean-ctx.md) is per-project. Without it, Kiro will default to its native tools and ignore the MCP server for reads and searches.

Verdent

Verdent supports MCP servers via configuration or CLI.

1. Open Verdent settings or navigate to the MCP section.
2. Run the init command:

   lean-ctx init --agent verdent

3. Or manually create the MCP config:

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

4. Restart Verdent to activate.

Note: Verdent's MCP support may require a recent version. Update Verdent if tools don't appear.

Other MCP-compatible tools

Any tool that supports the Model Context Protocol can use LeanCTX. The standard MCP config format is:

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

Key points:

• The command must point to the LeanCTX binary (use full path if not in PATH).
• No args or env are required - LeanCTX auto-configures.
• The binary communicates via stdio (standard MCP transport).
• After adding the config, restart your tool and verify LeanCTX tools appear.

lean-ctx onboard, the recommended first command

Connects every AI tool found on your machine using sensible defaults, with zero questions, then prints one clear "you're connected" message.

lean-ctx onboard

Under the hood, onboard runs the same engine as the full setup wizard, but in non-interactive mode, it makes every decision for you. Files changed: MCP config for each detected editor, the shell RC hook, and ~/.lean-ctx/ is created.

lean-ctx setup — the guided wizard (full control)

An interactive, 12-step wizard. Use it when you want to decide about the proxy, telemetry, auto-updates, compression level, and tool profile.

lean-ctx setup

The 12 steps

First-run menu

lean-ctx install

lean-ctx install runs the guided setup. install --repair (or --fix) runs the non-interactive, merge-based refresh.

lean-ctx install            # = lean-ctx setup
lean-ctx install --repair   # non-interactive repair (no deletes)

lean-ctx bootstrap — zero-config CI/scripts

Non-interactive setup + fix with sensible defaults. Identical to install --repair but named for automation.

lean-ctx bootstrap [--json]

lean-ctx init

• lean-ctx init --global — installs only the shell aliases/hook into your shell RC
• lean-ctx init --agent <name> — configures MCP + rules + skill for one specific agent (e.g. cursor, claude, codex, gemini)

lean-ctx doctor

Runs ~27 diagnostic checks across binary, data dir, MCP configs, shell hook, daemon, proxy, caches, and memory.

lean-ctx doctor                 # full diagnostics
lean-ctx doctor --fix           # auto-repair what's fixable
lean-ctx doctor --json          # machine-readable
lean-ctx doctor integrations    # per-IDE wiring health

lean-ctx status

A lighter-weight "am I connected?" report. Use status for a fast yes/no; use doctor for deep diagnostics.

lean-ctx status
lean-ctx status --json