SuperAPI AI Directory

lsp-setup

Coding & development

View repository

Updated 11-15 16:06

About this skill

LSP Setup

Configure LSP code intelligence for the current code repository so the AI coding agent can precisely locate symbols from the very first second.

Installation Scope

Category Install Location Why
LSP binaries (vtsls / gopls / pyright) Global (system tools) All projects share the same language server
Enable Claude Code LSP plugins ~/.claude/settings.json Plugin registration is global
LSP session hook Project .claude/hooks/lsp-session.sh Only sessions in this project are reminded to use LSP
hook configuration Project .claude/settings.local.json Project-level SessionStart hook
Codex lsp-mcp binary ~/.codex/tools/lsp-mcp/ One global copy of the tool itself
Codex lsp-mcp MCP registration ~/.codex/config.toml Codex MCP registration is global
Codex lsp-mcp project configuration Project .lsp-mcp.json Each project has different languages and presets
Retrieval rules Project CLAUDE.md / .codex/AGENTS.md Agent instructions follow the project
Local ignore Project .git/info/exclude Do not modify tracked .gitignore

Execution Flow

Step 1: Run the diagnostic script

bash ~/.claude/skills/lsp-setup/scripts/lsp-doctor.sh --project-dir "$(pwd)"

Check whether the output contains [MISSING]. If so, add --fix to auto-fix:

bash ~/.claude/skills/lsp-setup/scripts/lsp-doctor.sh --fix --project-dir "$(pwd)"

When installing only Codex LSP MCP, use narrow mode:

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}" bash ~/.claude/skills/lsp-setup/scripts/lsp-doctor.sh --fix --codex-lsp-only --project-dir "$(pwd)"

The script checks and fixes the following parts:

1a. Claude Code LSP plugins

Detect and complete:

  1. ENABLE_LSP_TOOL Environment variable → ~/.claude/settings.json
  2. Register marketplace → Piebald-AI/claude-code-lsps
  3. Enable language plugins → Automatically select based on project language vtsls/gopls/pyright/rust-analyzer

1b. LSP language server binaries

Project marker file LSP Server Install command
tsconfig.json / package.json vtsls npm i -g @vtsls/language-server
go.mod gopls go install golang.org/x/tools/gopls@latest
pyproject.toml / requirements.txt pyright pip3 install pyright
Cargo.toml rust-analyzer rustup component add rust-analyzer

1c. Codex LSP MCP

Check item When missing, --fix behavior
~/.codex/tools/lsp-mcp/target/release/lsp-mcp clone/build BumpyClock/lsp-mcp, apply compatibility patch
~/.codex/config.toml [mcp_servers.lsp-mcp] Write to global MCP registration, do not write a fixed --workspace-root
Project .lsp-mcp.json Write local configuration based on project language
Project .git/info/exclude Local ignore .lsp-mcp/、.lsp-mcp.json

Current patches fix: stale diagnostics filtering, documentSymbol not fetching snippets, nested symbols not hovered one by one, multi-byte character panic.

1d. Project dependencies

Lock file Command
pnpm-lock.yaml pnpm install --frozen-lockfile
package-lock.json npm ci
go.mod go mod download

1e. Retrieval rules

Automatically detectproject working directory's CLAUDE.md and .codex/AGENTS.md; if there is no "code retrieval" section, append one. If CLAUDE.md is already tracked by Git, do not modify it automatically, to avoid local AI retrieval instructions entering team PRs. The Codex version only writes the currently available tool set:documentSymbol、goToDefinition、findReferences、hover、getDiagnostics。

Step 2: Install the LSP session hook

Copy the hook script bundled with this skill tothe project working directory:

mkdir -p .claude/hooks
cp ~/.claude/skills/lsp-setup/hooks/lsp-session.sh .claude/hooks/lsp-session.sh
chmod +x .claude/hooks/lsp-session.sh

Inthe project .claude/settings.local.json Add a SessionStart hook in:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/lsp-session.sh"
          }
        ]
      }
    ]
  }
}

Note: userelative paths .claude/hooks/lsp-session.sh, do not write absolute paths.

Step 3: Local ignore

Confirm that .git/info/exclude contains:

.claude/hooks/
.claude/settings.local.json
.lsp-mcp/
.lsp-mcp.json

If the script cannot fix it

  • gopls cache is stale:pkill -f gopls, reopen the session
  • LSP first cold start is slow: wait 3-5 seconds and retry
  • node_modules is stale: delete node_modules and run again --fix
  • New Codex session did not expose the LSP MCP: confirm that ~/.codex/config.toml has [mcp_servers.lsp-mcp], and fully open a new Codex window