Editor Integrations

One-Shot Fix

If something broke after an update, run these commands in order:

lean-ctx init --global
lean-ctx init --agent cursor
lean-ctx doctor

After configuring an IDE, restart the IDE completely so it reconnects to MCP. MCP changes do not apply to an already running process.

IDE Matrix

Common MCP config locations and the fastest command to fix them:

If you are unsure, run lean-ctx doctor — it prints what it detected and what to fix.

Troubleshooting

It shows 0 tokens saved

This usually means MCP tools are not being used yet, or not enough commands were executed since last reset:

lean-ctx doctor
lean-ctx gain --reset
lean-ctx gain

MCP config points to an old binary path

If you switched install method (Homebrew / cargo / install.sh), update the MCP entry:

lean-ctx init --agent cursor
lean-ctx init --agent claude
lean-ctx setup

Homebrew link fails (binary already exists)

If you previously installed via cargo install, Homebrew may fail to link:

brew unlink lean-ctx || true
brew link --overwrite lean-ctx
lean-ctx --version

lean-ctx integrates with 24+ AI coding agents and editors using a combination of CLI-first hooks (where the client supports hook interception / a reliable terminal tool) and Model Context Protocol (MCP) (when you want explicit ctx_* tools). Each integration is auto-configured by lean-ctx init — or you can set it up manually using the guides below.

Modes: Every integration supports --mode: auto (recommended), cli-redirect (CLI-first), mcp (MCP tools), hybrid (both).

# Recommended (auto-detect best mode per tool)
lean-ctx init --agent cursor

# Force MCP tools (ctx_read, ctx_shell, ...)
lean-ctx init --agent cursor --mode mcp

# Force CLI-first (shell rewrite hooks + prefer lean-ctx read/grep/ls)
lean-ctx init --agent cursor --mode cli-redirect

# Combine both (fallback path available)
lean-ctx init --agent cursor --mode hybrid

Universal Setup

The fastest way to get lean-ctx running in any editor:

# Install lean-ctx
curl -fsSL https://leanctx.com/install.sh | sh

# Auto-detect and configure all installed editors
lean-ctx setup

# Premium repair (merge-based, idempotent)
lean-ctx install --repair

# Premium integration health checks (Cursor/Claude Code)
lean-ctx doctor integrations

# Or configure a specific editor
lean-ctx init --agent claude
lean-ctx init --agent cursor
lean-ctx init --agent codex
lean-ctx init --agent gemini
lean-ctx init --agent copilot

lean-ctx setup scans your system for installed editors and configures each one automatically. For individual control, use lean-ctx init --agent <name> with any of the agent keys listed below.

How It Works

lean-ctx integrates with editors at three levels:

1. CLI-first (recommended where supported) - hook interception rewrites common shell commands to lean-ctx -c, and agent rules prefer lean-ctx read/grep/ls for file operations (no MCP schema overhead).
2. MCP Server (optional) - lean-ctx can also run as a stdio-based MCP server, exposing ctx_read, ctx_shell, ctx_search, etc. Use --mode mcp or --mode hybrid when you want explicit MCP tools.
3. Rules + Hook Scripts - editor-specific rule files (e.g. .cursor/rules/lean-ctx.mdc, CLAUDE.md, AGENTS.md) set tool preferences, and hook scripts (Claude Code, Cursor, Codex, Gemini, Copilot, Qoder) can rewrite terminal commands transparently.

Claude Code

Claude Code gets the deepest integration: MCP server, PreToolUse hooks, CLAUDE.md rules, a dedicated skill, and auto-approved tools. The 2048-character system prompt limit means lean-ctx uses a layered approach.

Auto Setup

# Auto (recommended)
lean-ctx init --agent claude

# Force MCP tools
lean-ctx init --agent claude --mode mcp

What Gets Configured

MCP Configuration (only in MCP/Hybrid mode)

In ~/.claude.json (managed via claude mcp add-json when available):

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": {
        "LEAN_CTX_DATA_DIR": "~/.lean-ctx"
      }
    }
  }
}

PreToolUse Hooks

In ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|bash",
        "hooks": [{
          "type": "command",
          "command": "lean-ctx hook rewrite"
        }]
      },
      {
        "matcher": "Read|read|ReadFile|Grep|grep|Search|search|ListFiles|ListDirectory",
        "hooks": [{
          "type": "command",
          "command": "lean-ctx hook redirect"
        }]
      }
    ]
  }
}

The rewrite hook intercepts shell commands and wraps them with lean-ctx -c for output compression. The redirect hook is intentionally a pass-through (native tools remain available, which is required for reliable edits in many clients). Tool preference comes from injected rules: use ctx_* tools in --mode mcp/--mode hybrid, or use lean-ctx CLI commands in --mode cli-redirect.

Project-Level Hooks

For per-project hook configuration:

# Creates .claude/settings.local.json in the current project
lean-ctx init --agent claude --project

Quirks & Notes

• Claude Code has a 2048-character limit for MCP server instructions - lean-ctx uses external rule files to work around this.
• The autoApprove list covers all 46+ lean-ctx tools so they run without confirmation prompts.
• If claude CLI is available, lean-ctx init uses claude mcp add-json --scope user for reliable config.

Cursor

Cursor integrates via PreToolUse hooks and project rules. MCP is optional (use --mode mcp or --mode hybrid).

Auto Setup

lean-ctx init --agent cursor

What Gets Configured

MCP Configuration (only in MCP/Hybrid mode)

In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": {
        "LEAN_CTX_DATA_DIR": "~/.lean-ctx"
      }
    }
  }
}

Project Rules

The file .cursor/rules/lean-ctx.mdc is created in your project directory. It contains the full lean-ctx instruction set including tool mapping, CEP protocol, and CRP mode directives. In CLI-first mode it tells Cursor's AI to prefer lean-ctx CLI commands (lean-ctx read, lean-ctx grep, lean-ctx ls, lean-ctx -c) over native equivalents. In MCP/Hybrid mode it can also prefer ctx_* tools.

PreToolUse Hooks

In ~/.cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "matcher": "Shell",
        "command": "lean-ctx hook rewrite"
      },
      {
        "matcher": "Read|Grep",
        "command": "lean-ctx hook redirect"
      }
    ]
  }
}

Quirks & Notes

• The .mdc rule file is Cursor-specific Markdown with metadata headers.
• Restart Cursor after running lean-ctx init --agent cursor to activate hooks and rules (and MCP if you enabled it via --mode mcp/--mode hybrid).
• If you use Cursor in multiple projects, the MCP config is global but rules are per-project.

OpenAI Codex

Codex runs in Hybrid mode: MCP for Desktop and Cloud variants, plus CLI hooks for the terminal variant. All three share ~/.codex/config.toml.

Auto Setup

lean-ctx init --agent codex

What Gets Configured

MCP Configuration

In ~/.codex/config.toml:

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

[features]
codex_hooks = true

Hook Configuration

In ~/.codex/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear",
        "hooks": [{
          "type": "command",
          "command": "lean-ctx hook codex-session-start",
          "timeout": 15
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "lean-ctx hook codex-pretooluse",
          "timeout": 15
        }]
      }
    ]
  }
}

Quirks & Notes

• Codex uses TOML for MCP config - not JSON like most other editors.
• The codex_hooks = true feature flag must be enabled in config.toml for hooks to work.
• SessionStart hooks run when a session starts, resumes, or is cleared.
• lean-ctx auto-creates AGENTS.md in the project root with instructions.

Gemini CLI / Antigravity

Gemini CLI and Antigravity share the ~/.gemini directory but use different config formats. Important: Gemini CLI uses ~/.gemini/settings.json - not mcp.json.

Auto Setup

# Configures both Gemini CLI and Antigravity
lean-ctx init --agent gemini

Gemini CLI Configuration

In ~/.gemini/settings.json:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": {
        "LEAN_CTX_DATA_DIR": "~/.lean-ctx"
      },
      "trust": true
    }
  }
}

Gemini CLI Hooks

Gemini CLI also supports BeforeTool hooks in ~/.gemini/settings.json:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "shell|execute_command|run_shell_command",
        "hooks": [{
          "type": "command",
          "command": "lean-ctx hook rewrite"
        }]
      },
      {
        "matcher": "read_file|read_many_files|grep|search|list_dir",
        "hooks": [{
          "type": "command",
          "command": "lean-ctx hook redirect"
        }]
      }
    ]
  }
}

Antigravity Configuration

Antigravity uses a separate MCP config file at ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": {
        "LEAN_CTX_DATA_DIR": "~/.lean-ctx"
      }
    }
  }
}

Quirks & Notes

• Gemini CLI config is ~/.gemini/settings.json - not mcp.json. This is a common mistake.
• Antigravity does not receive autoApprove - it handles tool approval differently.
• Gemini uses BeforeTool (not PreToolUse) as the hook event name.
• The "trust": true flag is required for Gemini CLI to allow MCP tool execution.

GitHub Copilot (VS Code)

GitHub Copilot uses the VS Code MCP settings format plus a dedicated hooks file.

Auto Setup

# Project-level (recommended)
lean-ctx init --agent copilot

# Global (VS Code User settings)
lean-ctx init --agent copilot --global

What Gets Configured

MCP Configuration

In .vscode/mcp.json (project) or VS Code User settings (global):

{
  "servers": {
    "lean-ctx": {
      "type": "stdio",
      "command": "lean-ctx",
      "args": [],
      "env": {
        "LEAN_CTX_DATA_DIR": "~/.lean-ctx"
      }
    }
  }
}

PreToolUse Hooks

In .github/hooks/hooks.json:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "lean-ctx hook rewrite",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "lean-ctx hook redirect",
        "timeoutSec": 5
      }
    ]
  }
}

Quirks & Notes

• VS Code MCP uses "servers" (not "mcpServers") as the top-level key.
• Copilot hooks use "bash" instead of "command" for the script field.
• The --global flag writes to VS Code User-level settings instead of .vscode/.
• Hook location is .github/hooks/hooks.json (project) or ~/.github/hooks/hooks.json (global).

Windsurf

lean-ctx init --agent windsurf

MCP Configuration

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": { "LEAN_CTX_DATA_DIR": "~/.lean-ctx" }
    }
  }
}

Project Rules

lean-ctx creates a .windsurfrules file in your project root with shell-wrapping instructions. This tells Windsurf to prefix commands with lean-ctx -c for compression.

Cline / Roo Code

lean-ctx init --agent cline
lean-ctx init --agent roo

MCP Configuration

Both use the VS Code extension globalStorage MCP settings format:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": { "LEAN_CTX_DATA_DIR": "~/.lean-ctx" }
    }
  }
}

Project Rules

lean-ctx creates .clinerules in your project root with shell-wrapping instructions.

Quirks & Notes

• Config paths are in VS Code's globalStorage directory - platform-specific locations.
• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/ (Cline)
• macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/ (Roo)

Pi Coding Agent

lean-ctx init --agent pi

What Gets Configured

MCP Configuration

In ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": { "LEAN_CTX_DATA_DIR": "~/.lean-ctx" },
      "lifecycle": "lazy",
      "directTools": true
    }
  }
}

lean-ctx also installs the pi-lean-ctx Pi package via pi install npm:pi-lean-ctx, which routes all Pi tools (bash, read, grep, find, ls) through lean-ctx for compression.

AWS Kiro

lean-ctx init --agent kiro

What Gets Configured

MCP Configuration

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": { "LEAN_CTX_DATA_DIR": "~/.lean-ctx" }
    }
  }
}

Kiro uses steering files instead of rule files. lean-ctx creates .kiro/steering/lean-ctx.md in your project root with tool preference instructions.

Zed

lean-ctx setup  # Auto-detects Zed

MCP Configuration

Zed uses a unique context_servers format in its settings:

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

Quirks & Notes

• Zed uses "context_servers" instead of "mcpServers".
• The "source": "custom" field is required for Zed to recognize the server.
• Zed's config location is platform-specific: ~/.config/zed/settings.json (Linux) or ~/Library/Application Support/Zed/settings.json (macOS).

Hermes Agent

lean-ctx init --agent hermes

Hermes uses YAML configuration at ~/.hermes/config.yaml:

mcp_servers:
  lean-ctx:
    command: "lean-ctx"
    env:
      LEAN_CTX_DATA_DIR: "~/.lean-ctx"

lean-ctx also creates ~/.hermes/HERMES.md with tool preference rules and optionally a project-level .hermes.md.

Amp

lean-ctx init --agent amp

In ~/.config/amp/settings.json:

{
  "amp.mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": { "LEAN_CTX_DATA_DIR": "~/.lean-ctx" }
    }
  }
}

Amp uses "amp.mcpServers" as the key - not "mcpServers".

JetBrains IDEs

lean-ctx init --agent jetbrains

JetBrains uses an array-based server format at ~/.jb-mcp.json:

{
  "servers": [
    {
      "name": "lean-ctx",
      "command": "lean-ctx",
      "args": [],
      "env": {
        "LEAN_CTX_DATA_DIR": "~/.lean-ctx"
      }
    }
  ]
}

Works with IntelliJ IDEA, WebStorm, PyCharm, GoLand, and all JetBrains IDEs that support MCP.

OpenCode

lean-ctx init --agent opencode

In ~/.config/opencode/opencode.json:

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

OpenCode uses "type": "local", wraps command in an array, and uses "environment" instead of "env". lean-ctx also installs an OpenCode plugin at ~/.config/opencode/plugins/lean-ctx.ts.

Other Editors

The following editors use standard mcpServers JSON format. Run lean-ctx init --agent <key> or lean-ctx setup to auto-configure:

Standard mcpServers JSON format (used by Verdent, Qwen, Trae, Amazon Q):

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "env": { "LEAN_CTX_DATA_DIR": "~/.lean-ctx" }
    }
  }
}

Crush uses a slightly different structure with "mcp" as root key:

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

Verifying Your Setup

After configuring any editor, verify lean-ctx is connected:

# Check lean-ctx health
lean-ctx doctor

# Premium integration health (Cursor/Claude Code)
lean-ctx doctor integrations

# Repair drift (safe, merge-based)
lean-ctx install --repair

# In Claude Code:
/mcp          # Should show lean-ctx as connected
/memory       # Should show CLAUDE.md loaded

# In Cursor:
# Check MCP panel in settings - lean-ctx should appear as "connected"

# In any editor with MCP:
# Call ctx_overview() - should return project summary