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:
ENABLE_LSP_TOOLEnvironment variable →~/.claude/settings.json- Register marketplace →
Piebald-AI/claude-code-lsps - 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_modulesand run again--fix - New Codex session did not expose the LSP MCP: confirm that
~/.codex/config.tomlhas[mcp_servers.lsp-mcp], and fully open a new Codex window