Getting Started

Step 1: Install the Binary

Universal Installer (any platform)

The fastest way to install lean-ctx 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 /usr/local/bin. 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 lean-ctx to your AI coding tool by adding it as an MCP server.

# macOS / Linux:
which lean-ctx
# Example output: /opt/homebrew/bin/lean-ctx  or  /Users/you/.cargo/bin/lean-ctx

# Windows (PowerShell):
where.exe lean-ctx
# Example output: C:\Users\you\.cargo\bin\lean-ctx.exe

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 - lean-ctx should show as "connected".

Optional: install agent rules to make Cursor prefer lean-ctx 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 creates a CLAUDE.md file that teaches Claude to use lean-ctx tools instead of native file reads and shell commands.

Claude Code: 2048-Character Limit

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

lean-ctx handles this automatically: lean-ctx init --agent claude installs the full instructions as a Claude Rules file (~/.claude/rules/lean-ctx.md) and an Agent Skill (~/.claude/skills/lean-ctx/). 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. Installs full instructions to ~/.claude/rules/lean-ctx.md
# 3. Installs Agent Skill to ~/.claude/skills/lean-ctx/

If you installed lean-ctx manually (without init), copy the rules file: lean-ctx init --agent claude to retroactively install rules + skills.

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 lean-ctx 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: lean-ctx tools should appear in the assistant panel.

Tip: Run lean-ctx init --agent zed to install agent rules that make Zed prefer lean-ctx tools.

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

Antigravity uses the same MCP config format as Gemini CLI but in a separate directory.

1. Create the Antigravity MCP 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. Paste this JSON:

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

   Important: If Antigravity can't find the binary, use the full absolute path to lean-ctx.

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

You can also manage MCP servers via Antigravity's built-in server management UI.

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. You can add lean-ctx from the settings UI or via CLI.

1. Open OpenClaw settings and navigate to the MCP servers section.
2. Add a new MCP server with command: lean-ctx
3. Restart OpenClaw to activate.

Tip: Run lean-ctx init --agent openclaw to install lean-ctx skills for OpenClaw.

Pi

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

1. Make sure lean-ctx is installed:

   cargo install lean-ctx

2. Install the Pi plugin:

   pi install npm:pi-lean-ctx

   Or use lean-ctx's built-in command:

   lean-ctx init --agent pi

3. Restart Pi.
4. Verify: lean-ctx tools should appear in Pi's tool list.

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

AWS Kiro

AWS Kiro requires both an MCP config and a steering file to use lean-ctx 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 lean-ctx. The standard MCP config format is:

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

Key points:

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