Erste Schritte

Schritt 1: Binary installieren

Universal-Installer (alle Plattformen)

Der schnellste Weg, lean-ctx ohne Voraussetzungen zu installieren:

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

Das Installationsskript erkennt dein Betriebssystem und die Architektur, lädt die richtige Binary herunter und platziert sie in /usr/local/bin. Es funktioniert auf macOS, Linux und WSL.

Wenn du das Skript vor der Ausführung überprüfen möchtest:

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)

Installiere das vorkompilierte Binary über npm - keine Rust-Toolchain erforderlich:

npm install -g lean-ctx-bin

Lädt das korrekte Binary für deine Plattform während postinstall mit SHA256-Verifizierung herunter. Funktioniert auf macOS (Intel + Apple Silicon), Linux (x86_64) und Windows (x86_64).

macOS

Option A: Homebrew (empfohlen)

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

Homebrew kümmert sich automatisch um Updates und den PATH.

Option B: Cargo (aus Quellcode kompilieren)

cargo install lean-ctx

Falls lean-ctx nach der Installation nicht gefunden wird, füge Cargos bin-Verzeichnis zum PATH hinzu:

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

Option C: Manueller Binary-Download

1. Lade die Binary für deine Architektur von GitHub Releases herunter:
   • lean-ctx-aarch64-apple-darwin.tar.gz (Apple Silicon / M1+)
   • lean-ctx-x86_64-apple-darwin.tar.gz (Intel)
2. Entpacken und in den PATH verschieben:

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

Falls macOS die Binary mit einer Gatekeeper-Warnung blockiert, entferne das Quarantäne-Attribut:

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

Funktioniert mit jedem AUR-Helper: yay, paru, trizen, etc.

Option C: Cargo (aus Quellcode kompilieren)

cargo install lean-ctx

Erfordert die Rust-Toolchain. Installiere sie über rustup.rs falls nötig.

Option D: Manueller Binary-Download

1. Lade lean-ctx-x86_64-unknown-linux-gnu.tar.gz von GitHub Releases herunter
2. Entpacken und in den PATH verschieben:

   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 (empfohlen)

1. Lade lean-ctx-x86_64-pc-windows-msvc.zip von GitHub Releases herunter
2. Entpacke die .zip-Datei
3. Öffne den entpackten Ordner - du siehst lean-ctx.exe
4. Verschiebe lean-ctx.exe in einen Ordner in deinem PATH, zum Beispiel:

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

5. Füge den Ordner zu deinem PATH hinzu, falls noch nicht geschehen:
   • Öffne Einstellungen → System → Info → Erweiterte Systemeinstellungen
   • Klicke auf Umgebungsvariablen
   • Unter Benutzervariablen wähle Path, klicke Bearbeiten, dann Neu
   • Füge den Pfad zu deinem bin-Ordner hinzu (z.B. C:\Users\du\bin)
6. Öffne ein neues PowerShell- oder CMD-Fenster und überprüfe:

   lean-ctx --version

Option B: Cargo (aus Quellcode kompilieren)

1. Installiere Rust, falls noch nicht installiert
2. Kompilieren und installieren:

   cargo install lean-ctx

3. Die Binary wird in %USERPROFILE%\.cargo\bin\ platziert, was normalerweise bereits im PATH ist.

Option C: Aus Quellcode bauen (klonen & kompilieren)

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-Benutzer: Wenn du WSL verwendest, folge stattdessen der Linux-Anleitung.

Aus dem Quellcode bauen (alle Plattformen)

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

Das Binary befindet sich unter target/release/lean-ctx (oder lean-ctx.exe unter Windows). Kopiere es in ein Verzeichnis in deinem PATH.

nur wenn lean-ctx setup nicht funktioniert hat

Verbinde lean-ctx mit deinem KI-Coding-Tool, indem du es als MCP-Server hinzufügst.

# 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. Erstelle oder bearbeite die MCP-Konfigurationsdatei:

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

2. Füge dieses JSON ein:

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

3. Starte Cursor vollständig neu (Cmd+Q / Alt+F4, dann erneut öffnen).
4. Überprüfe: Öffne das MCP-Panel in den Einstellungen - lean-ctx sollte als "verbunden" angezeigt werden.

Optional: Installiere Agenten-Regeln, damit Cursor lean-ctx-Tools bevorzugt:

lean-ctx init --agent cursor

Claude Code

Claude Code hat eingebaute MCP-Unterstützung. Keine Konfigurationsdatei nötig:

# 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

Der Init-Befehl erstellt eine CLAUDE.md-Datei, die Claude anweist, lean-ctx-Tools statt nativer Datei-Lese- und Shell-Befehle zu verwenden.

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.

Hinweis: GitHub Copilot MCP-Unterstützung erfordert VS Code 1.99+ und die neueste Copilot-Erweiterung. Copilot CLI verwendet .github/mcp.json mit dem mcpServers-Schlüssel; VS Code Copilot verwendet .vscode/mcp.json mit dem servers-Schlüssel.

Pro Projekt: Diese Konfigurationen gelten pro Projekt. Committe sie, um sie mit deinem Team zu teilen.

Windsurf

1. Öffne die MCP-Konfigurationsdatei:

   # 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. Füge dieses JSON ein:

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

   Wichtig: Windsurf benötigt den vollständigen absoluten Pfad zur Binary. Beispiel für Homebrew auf macOS:

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

3. Starte Windsurf vollständig neu.
4. Überprüfe die MCP-Verbindung in den Windsurf-Einstellungen.

Zed

1. Öffne die Zed-Einstellungen:

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

2. Füge die lean-ctx Context-Server-Konfiguration hinzu:

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

   Hinweis: Zed verwendet context_servers (nicht mcpServers) und erfordert source: "custom".

3. Speichern und Zed neu starten.
4. Überprüfe: lean-ctx-Tools sollten im Assistenten-Panel erscheinen.

Tipp: Führe lean-ctx init --agent zed aus, um Agenten-Regeln zu installieren, die Zed dazu bringen, lean-ctx-Tools zu bevorzugen.

OpenAI Codex CLI

1. Erstelle oder bearbeite die Codex-Konfigurationsdatei:

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

2. Füge den MCP-Server-Eintrag hinzu:

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

3. Starte Codex CLI neu.

Alternativ: Verwende den eingebauten Codex-CLI-Befehl:

codex mcp add lean-ctx

Installiere Agenten-Anweisungen für Codex:

lean-ctx init --agent codex

Gemini CLI

1. Erstelle oder bearbeite die Gemini-MCP-Konfiguration:

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

2. Füge die MCP-Server-Konfiguration hinzu:

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

   Wichtig: Falls Gemini die Binary nicht findet, verwende den vollständigen Pfad. Beispiel für Homebrew auf macOS:

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

3. Starte Gemini CLI neu.
4. Überprüfe mit einem Prompt, der Tool-Nutzung auslöst.

Bekanntes Problem: Gemini CLI ruft MCP-Tools möglicherweise nicht immer konsistent auf. Wenn Tools nicht ausgelöst werden, versuche lean-ctx init --agent gemini, um eine GEMINI.md mit Nutzungsanweisungen zu installieren.

Antigravity

Antigravity verwendet das gleiche MCP-Konfigurationsformat wie Gemini CLI, aber in einem separaten Verzeichnis.

1. Erstelle das Antigravity-MCP-Konfigurationsverzeichnis und die Datei:

   # 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. Füge dieses JSON ein:

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

   Wichtig: Falls Antigravity die Binary nicht findet, verwende den vollständigen absoluten Pfad zu lean-ctx.

3. Starte Antigravity neu.
4. Überprüfe mit einem Prompt, der Tool-Nutzung auslöst.

Du kannst MCP-Server auch über die eingebaute Server-Verwaltungsoberfläche von Antigravity verwalten.

OpenCode

1. Erstelle oder bearbeite die OpenCode-Konfigurationsdatei:

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

2. Füge die MCP-Server-Konfiguration hinzu:

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

3. Starte OpenCode neu.

OpenClaw

OpenClaw unterstützt MCP-Server nativ. Du kannst lean-ctx über die Einstellungsoberfläche oder per CLI hinzufügen.

1. Öffne die OpenClaw-Einstellungen und navigiere zum MCP-Server-Bereich.
2. Füge einen neuen MCP-Server mit dem Befehl lean-ctx hinzu
3. Starte OpenClaw neu, um zu aktivieren.

Tipp: Führe lean-ctx init --agent openclaw aus, um lean-ctx Skills für OpenClaw zu installieren.

Pi

Pi hat ein dediziertes lean-ctx Plugin (pi-lean-ctx), das sich automatisch integriert.

1. Stelle sicher, dass lean-ctx installiert ist:

   cargo install lean-ctx

2. Installiere das Pi-Plugin:

   pi install npm:pi-lean-ctx

   Oder verwende den eingebauten lean-ctx-Befehl:

   lean-ctx init --agent pi

3. Starte Pi neu.
4. Überprüfe: lean-ctx-Tools sollten in Pis Tool-Liste erscheinen.

Hinweis: Pis Smart Reads verwenden automatisch lean-ctx, wenn das Plugin installiert ist. Keine zusätzliche Konfiguration nötig.

AWS Kiro

AWS Kiro benötigt sowohl eine MCP-Konfiguration als auch eine Steering-Datei, um lean-ctx-Tools anstelle nativer Äquivalente zu verwenden.

1. Führe lean-ctx setup aus - Kiro wird automatisch erkannt und sowohl MCP-Konfiguration als auch Steering-Datei werden erstellt.
2. Oder verwende den dedizierten Befehl (erstellt beide Dateien):

   lean-ctx init --agent kiro

3. Dies erstellt zwei Dateien:
   • ~/.kiro/settings/mcp.json - MCP-Server-Verbindung
   • .kiro/steering/lean-ctx.md - Steering-Datei, die Kiro anweist, mcp_lean_ctx_ctx_read statt readFile zu bevorzugen, usw.
4. Starte Kiro neu, um zu aktivieren.

Wichtig: Die Steering-Datei (.kiro/steering/lean-ctx.md) ist projektspezifisch. Ohne sie verwendet Kiro standardmäßig seine nativen Tools und ignoriert den MCP-Server für Lese- und Suchvorgänge.

Verdent

Verdent unterstützt MCP-Server über Konfiguration oder CLI.

1. Öffne die Verdent-Einstellungen oder navigiere zum MCP-Bereich.
2. Führe den Init-Befehl aus:

   lean-ctx init --agent verdent

3. Oder erstelle die MCP-Konfiguration manuell:

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

4. Starte Verdent neu, um zu aktivieren.

Hinweis: Verdents MCP-Unterstützung erfordert möglicherweise eine aktuelle Version. Aktualisiere Verdent, wenn Tools nicht erscheinen.

Andere MCP-kompatible Tools

Jedes Tool, das das Model Context Protocol unterstützt, kann lean-ctx verwenden. Das Standard-MCP-Konfigurationsformat ist:

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

Wichtige Punkte:

• Der command muss auf die lean-ctx Binary zeigen (verwende den vollständigen Pfad, wenn nicht im PATH).
• Keine args oder env erforderlich - lean-ctx konfiguriert sich automatisch.
• Die Binary kommuniziert über stdio (Standard-MCP-Transport).
• Nach dem Hinzufügen der Konfiguration starte dein Tool neu und überprüfe, ob lean-ctx-Tools verfügbar sind.