Lsp Integration

LSP Integration for Claude Code Plugins

Overview

Language Server Protocol (LSP) servers provide code intelligence features like go-to-definition, find references, and hover information. Claude Code plugins can bundle or configure LSP servers to enhance Claude's understanding of code.

Key capabilities:

• Enable go-to-definition for code navigation
• Find all references to symbols
• Get hover information and documentation
• Support language-specific features (completions, diagnostics)

LSP Server Configuration

Plugins can provide LSP servers in the plugin manifest:

Basic Configuration

{
  "name": "my-plugin",
  "lspServers": {
    "python": {
      "command": "pyright-langserver",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".py": "python",
        ".pyi": "python"
      }
    }
  }
}

Separate File Configuration

LSP servers can also be configured in a separate .lsp.json file at the plugin root:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Reference this file in plugin.json:

{
  "name": "my-plugin",
  "lspServers": "./.lsp.json"
}

Configuration Fields

command (required): The LSP server executable

args (optional): Command-line arguments for the server

extensionToLanguage (required): Maps file extensions to language IDs

{
  "extensionToLanguage": {
    ".py": "python",
    ".pyi": "python",
    ".pyw": "python"
  }
}

env (optional): Environment variables for the server process

{
  "env": {
    "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/lib"
  }
}

transport (optional): Communication transport - stdio (default) or socket

{
  "lspServers": {
    "dart": {
      "transport": "socket",
      "command": "dart",
      "args": ["language-server", "--port", "8123"],
      "extensionToLanguage": { ".dart": "dart" }
    }
  }
}

Socket transport connects to the server via TCP port instead of stdin/stdout.

initializationOptions (optional): Options passed to the server during LSP initialization

{
  "initializationOptions": {
    "typescript": {
      "tsdk": "./node_modules/typescript/lib"
    },
    "diagnostics": true,
    "formatting": { "tabSize": 2 }
  }
}

settings (optional): Settings passed via workspace/didChangeConfiguration

workspaceFolder (optional): Workspace folder path for the server

startupTimeout (optional): Maximum time to wait for server startup in milliseconds

shutdownTimeout (optional): Maximum time to wait for graceful shutdown in milliseconds

restartOnCrash (optional): Whether to automatically restart the server if it crashes

maxRestarts (optional): Maximum number of restart attempts before giving up

What Claude Gains from LSP

When an LSP plugin is installed and its language server binary is available, Claude gains two key capabilities:

Automatic Diagnostics

After every file edit Claude makes, the language server analyzes the changes and reports errors and warnings back automatically. Claude sees type errors, missing imports, and syntax issues without needing to run a compiler or linter. If Claude introduces an error, it notices and fixes the issue in the same turn.

Code Navigation

Claude can use the language server to:

• Jump to definitions
• Find all references to a symbol
• Get type information on hover
• List symbols in a file
• Find implementations of interfaces
• Trace call hierarchies

These operations give Claude more precise navigation than grep-based search.

Pre-built LSP Plugins

Claude Code provides official LSP plugins for common languages. Install from the marketplace:

Install the language server binary first, then install the plugin:

# Example: Python
pip install pyright  # or: npm install -g pyright
claude /install-plugin pyright-lsp

Troubleshooting: If you see Executable not found in $PATH in the /plugin Errors tab, install the required binary from the table above.

Creating Custom LSP Integration

Step 1: Choose or Build LSP Server

Options:

1. Use existing LSP server - Most languages have official or community servers
2. Bundle with plugin - Include server binary in plugin
3. Require user installation - Document server installation in README

Step 2: Configure in plugin.json

{
  "name": "go-lsp",
  "version": "1.0.0",
  "description": "Go language server integration",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go",
        ".mod": "go.mod"
      }
    }
  }
}

Step 3: Bundle Server (Optional)

For self-contained plugins, bundle the server:

my-lsp-plugin/
├── .claude-plugin/
│   └── plugin.json
└── servers/
    └── my-lsp-server

Use ${CLAUDE_PLUGIN_ROOT} for the command path:

{
  "lspServers": {
    "mylang": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-lsp-server",
      "args": ["--stdio"]
    }
  }
}

Step 4: Document Requirements

In your plugin README:

• List required external dependencies
• Provide installation instructions
• Note supported language versions
• Describe available features

Extension to Language Mapping

The extensionToLanguage field maps file extensions to LSP language identifiers:

Common Mappings

{
  "extensionToLanguage": {
    ".py": "python",
    ".js": "javascript",
    ".ts": "typescript",
    ".jsx": "javascriptreact",
    ".tsx": "typescriptreact",
    ".rs": "rust",
    ".go": "go",
    ".java": "java",
    ".rb": "ruby",
    ".php": "php",
    ".c": "c",
    ".cpp": "cpp",
    ".h": "c",
    ".hpp": "cpp",
    ".cs": "csharp"
  }
}

Multiple Extensions

A single language can have multiple extensions:

{
  "extensionToLanguage": {
    ".ts": "typescript",
    ".mts": "typescript",
    ".cts": "typescript",
    ".d.ts": "typescript"
  }
}

LSP Server Lifecycle

Startup

LSP servers start automatically when:

1. Claude Code session begins
2. Plugin with LSP server is enabled
3. User opens a file matching configured extensions

Communication

• Uses stdio for client-server communication
• Follows LSP specification for messages
• Claude Code manages the connection

Shutdown

Servers terminate when:

• Claude Code session ends
• Plugin is disabled
• Server crashes (auto-restart may occur)

Best Practices

Performance

1. Lazy initialization - Servers start when needed, not at session start
2. Minimal configuration - Only enable features you need
3. Resource limits - Consider memory/CPU impact of servers

Compatibility

1. Check LSP version - Ensure server supports required protocol version
2. Test cross-platform - Verify on macOS, Linux, Windows
3. Handle missing servers - Gracefully degrade if server not installed

Documentation

1. List prerequisites - External tools, versions required
2. Provide setup guide - Step-by-step installation
3. Document features - Which LSP capabilities are supported

Troubleshooting

Server Not Starting

Check:

• Command path is correct
• Server is installed and executable
• Required dependencies are available
• ${CLAUDE_PLUGIN_ROOT} is used for bundled servers

No Code Intelligence

Check:

• File extension matches extensionToLanguage mapping
• Language ID is correct for the server
• Server supports the requested feature

Debug Mode

Enable debug logging:

claude --debug

Look for:

• LSP server startup messages
• Communication logs
• Error responses

Quick Reference

Minimal LSP Configuration

{
  "lspServers": {
    "language": {
      "command": "server-command",
      "extensionToLanguage": {
        ".ext": "language-id"
      }
    }
  }
}

Full LSP Configuration

{
  "lspServers": {
    "language": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/lsp-server",
      "args": ["--stdio", "--log-level", "warn"],
      "extensionToLanguage": {
        ".ext1": "language",
        ".ext2": "language"
      },
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config"
      },
      "transport": "stdio",
      "initializationOptions": {},
      "settings": {},
      "workspaceFolder": ".",
      "startupTimeout": 10000,
      "shutdownTimeout": 5000,
      "restartOnCrash": true,
      "maxRestarts": 3
    }
  }
}

Best Practices Summary

DO:

• Use ${CLAUDE_PLUGIN_ROOT} for bundled server paths
• Map all relevant file extensions
• Document external dependencies
• Test on multiple platforms
• Handle server unavailability gracefully

DON'T:

• Hardcode absolute paths
• Assume servers are pre-installed
• Bundle large binaries without consideration
• Ignore server startup errors

Additional Resources

Reference Files

For detailed information, consult:

• references/popular-lsp-servers.md - Curated list of LSP servers by language with installation commands
• references/lsp-capabilities.md - LSP protocol capabilities and what they enable

Examples

• examples/minimal-lsp-plugin/ - Complete directory structure for a minimal LSP plugin
• examples/lsp-json-configs.md - Various .lsp.json configuration patterns

External Resources

• LSP Specification: https://microsoft.github.io/language-server-protocol/
• Claude Code Plugins Reference: https://docs.anthropic.com/en/docs/claude-code/plugins-reference
• Language Server List: https://langserver.org/