Começando

Etapa 1: Instalar o Binário

Instalador Universal (qualquer plataforma)

A forma mais rápida de instalar o lean-ctx sem pré-requisitos:

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)

Instale o binário pré-compilado via npm - sem necessidade de toolchain Rust:

npm install -g lean-ctx-bin

Isso baixa o binário correto para sua plataforma durante o postinstall com verificação SHA256. Funciona em macOS (Intel + Apple Silicon), Linux (x86_64) e 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.

Compilar a partir do código-fonte (qualquer plataforma)

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

O binário fica em target/release/lean-ctx (ou lean-ctx.exe no Windows). Copie-o para um diretório no seu PATH.

apenas se o lean-ctx setup não funcionou

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 requer tanto uma configuração MCP quanto um arquivo de steering para usar as ferramentas lean-ctx em vez dos equivalentes nativos.

1. Execute lean-ctx setup - o Kiro é detectado automaticamente e tanto a configuração MCP quanto o arquivo de steering são criados.
2. Ou use o comando dedicado (cria ambos os arquivos):

   lean-ctx init --agent kiro

3. Isso cria dois arquivos:
   • ~/.kiro/settings/mcp.json - Conexão do servidor MCP
   • .kiro/steering/lean-ctx.md - Arquivo de steering que instrui o Kiro a preferir mcp_lean_ctx_ctx_read em vez de readFile, etc.
4. Reinicie o Kiro para ativar.

Importante: O arquivo de steering (.kiro/steering/lean-ctx.md) é por projeto. Sem ele, o Kiro usará suas ferramentas nativas por padrão e ignorará o servidor MCP para leituras e buscas.

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.