Démarrage

Étape 1 : Installer le binaire

Installateur universel (toute plateforme)

Le moyen le plus rapide d'installer lean-ctx sans aucun prérequis :

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)

Installez le binaire précompilé via npm - aucune toolchain Rust requise :

npm install -g lean-ctx-bin

Cela télécharge le binaire adapté à votre plateforme pendant le postinstall avec vérification SHA256. Fonctionne sur macOS (Intel + Apple Silicon), Linux (x86_64) et 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.

Compiler depuis les sources (toute plateforme)

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

Le binaire se trouve dans target/release/lean-ctx (ou lean-ctx.exe sous Windows). Copiez-le dans un répertoire de votre PATH.

uniquement si lean-ctx setup n'a pas fonctionné

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.

Per-project: This config is per-project. Add .github/mcp.json to your .gitignore or commit it 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 nécessite à la fois une configuration MCP et un fichier de steering pour utiliser les outils lean-ctx au lieu des équivalents natifs.

1. Exécutez lean-ctx setup - Kiro est détecté automatiquement et la configuration MCP ainsi que le fichier de steering sont créés.
2. Ou utilisez la commande dédiée (crée les deux fichiers) :

   lean-ctx init --agent kiro

3. Cela crée deux fichiers :
   • ~/.kiro/settings/mcp.json - Connexion au serveur MCP
   • .kiro/steering/lean-ctx.md - Fichier de steering qui indique à Kiro de préférer mcp_lean_ctx_ctx_read à readFile, etc.
4. Redémarrez Kiro pour activer.

Important : Le fichier de steering (.kiro/steering/lean-ctx.md) est par projet. Sans lui, Kiro utilisera par défaut ses outils natifs et ignorera le serveur MCP pour les lectures et recherches.

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.