lsp-setup

LSP Setup for Claude Code Projects

Set up Language Server Protocol support in Claude Code for the current project. This enables semantic code intelligence: go-to-definition, find-references, hover, document symbols, workspace symbols, diagnostics, and call hierarchy — all at ~50ms instead of 30-60s grep-based navigation.

State Detection

This skill operates as a state machine. On each invocation, detect the current state and resume from the appropriate step:

1. No LSP configured → Start from Step 1 (detect languages)
2. Binaries missing → Resume at Step 3 (install binaries)
3. Plugins not installed → Resume at Step 4 (install plugins)
4. Plugins installed but LSP returns "No LSP server available" → Step 5 (restart needed)
5. LSP responds with symbols → Step 6 (validation complete, report success)

To detect state quickly: attempt an LSP documentSymbol call on any source file in the project. If it returns results, skip to validation. If "No LSP server available", check whether plugins are installed and binaries are on PATH.

Step 1: Detect Environment

Determine the current environment by checking uname -s:

• MINGW* or MSYS* → MINGW (Git Bash on Windows)
• /proc/version contains "microsoft" → WSL
• Darwin → macOS
• Otherwise → Linux

This affects install commands and PATH gotchas. Consult references/gotchas.md for environment-specific issues.

Step 2: Detect Languages

Scan the current project directory for language indicators using Glob. Check for source files (**/*.py, **/*.ts, **/*.cs, etc.) and project markers (**/pyproject.toml, **/tsconfig.json, **/Cargo.toml, etc.).

The complete detection pattern table is in references/lsp-registry.md under "Auto-Detection File Patterns" — use that as the authoritative source.

Present detected languages for confirmation. If a detected language has no official Claude Code LSP plugin, inform the user and ask whether to skip it.

Only the 12 languages in references/lsp-registry.md have official plugins. If auto-detection finds no supported languages, present the full list and let the user pick.

Step 3: Install Language Server Binaries

The verify script accepts lowercase identifiers, not registry display names. Map detected languages before invoking:

Registry Name	Script Identifier
C#	csharp
C/C++	cpp
TypeScript/JS	typescript

All other languages use their lowercase name (e.g., python, go, rust, java, kotlin, lua, php, ruby, swift).

Run the verify script to check all binaries at once:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/verify-lsp.sh <lang1> <lang2> ...

For any missing binary, look up the install command in references/lsp-registry.md and run it. Consult references/gotchas.md for environment-specific issues before running install commands.

Step 4: Configure and Install Plugins

4a: Global Settings

Check ~/.claude/settings.json for the ENABLE_LSP_TOOL env var. If missing, add it:

{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  }
}

The settings.json env block is the primary mechanism. As a supplementary fallback, also add export ENABLE_LSP_TOOL=1 to ~/.bashrc or ~/.zshrc if not already present.

4b: Marketplace and Plugin Installation

Verify the official marketplace is configured:

claude plugin marketplace list

If claude-plugins-official is not listed, add it. Run claude plugin marketplace add --help to see the required arguments, then add the marketplace. Once configured, update to fetch the latest catalog:

claude plugin marketplace update claude-plugins-official

For each language, install the corresponding plugin:

claude plugin install <plugin-name>@claude-plugins-official

Refer to references/lsp-registry.md for the language-to-plugin mapping.

4c: Enable in Project Settings

Verify each plugin is enabled in the project's .claude/settings.json:

{
  "enabledPlugins": {
    "<plugin-name>@claude-plugins-official": true
  }
}

4d: Verify Plugin Status

Run claude plugin list and confirm each LSP plugin shows as enabled. If any show as disabled, run claude plugin enable <name>.

Step 5: Session Restart

Critical: LSP servers require a full Claude Code restart to activate. /reload-plugins is NOT sufficient — it explicitly says "Restart to activate N LSP servers provided by plugins."

Display this message to the user:

LSP plugins are installed and configured. A full Claude Code restart is required to activate the LSP servers.

Please run /exit, then relaunch Claude Code. After restart, re-invoke this skill (say "validate LSP" or "check LSP setup") to confirm everything works.

If the user provides a session ID, suggest: claude --resume <session-id>.

Step 6: Validate LSP

After restart, validate each language:

1. Find a representative source file for each configured language
2. Run LSP documentSymbol on that file
3. If symbols are returned → that language's LSP is working
4. If "No LSP server available" → check binary PATH and plugin status

Also check debug logs:

grep "LSP servers loaded" ~/.claude/debug/latest

Report results per language:

| Language   | Binary    | Plugin        | Status  |
|------------|-----------|---------------|---------|
| Python     | pyright   | pyright-lsp   | Working |
| TypeScript | ts-ls     | typescript-lsp| Working |
| C#         | csharp-ls | csharp-lsp    | Failed  |

For any failures, consult references/gotchas.md and attempt remediation.

Reference Files

• references/lsp-registry.md — Complete plugin-to-binary mapping, install commands, auto-detection patterns
• references/gotchas.md — Environment-specific issues, troubleshooting, binary verification commands
• scripts/verify-lsp.sh — Automated binary and environment verification for detected languages

LSP Capabilities After Setup

Once configured, the LSP tool provides these operations on project files:

• goToDefinition — Jump to symbol source (~50ms)
• findReferences — All usages across the codebase
• hover — Type signatures and documentation
• documentSymbol — All symbols in a file
• workspaceSymbol — Search symbols across the project
• goToImplementation — Concrete implementations of interfaces
• incomingCalls / outgoingCalls — Call hierarchy tracing
• diagnostics — Real-time type checking and error detection