LSP Servers

Language Server Protocol (LSP) support gives opencode deep code intelligence capabilities. When enabled, opencode can query language servers for definitions, references, hover information, symbols, call hierarchies, and more.

Enabling LSP

Enable LSP globally by setting the lsp key to true in opencode.json:

{
  "lsp": true
}

When enabled, opencode automatically starts the appropriate LSP server for each detected language in your workspace.

Supported Languages and Servers

opencode includes built-in support for the following language servers:

Language	Server	Notes
TypeScript / JavaScript	typescript-language-server	Full TS/JS support
Python	pyright or pylsp	Configurable via settings
Rust	rust-analyzer	Requires Rust toolchain
Go	gopls	Standard Go LSP
Java	eclipse-jdtls	Requires JDK
C / C++	clangd	Requires clang tools
Ruby	solargraph	Requires gem installation
PHP	intelephense	PHP language server
HTML / CSS / JSON	vscode-langservers-extracted	Built-in web support
YAML	yaml-language-server	YAML validation
Markdown	marksman	Markdown intelligence
Lua	lua-language-server	Lua development
Shell	bash-language-server	Shell scripting

Automatic LSP server downloads can be disabled:

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

Configuring Individual Servers

You can disable specific language servers while keeping LSP enabled for others:

{
  "lsp": {
    "typescript": { "disabled": true },
    "python": { "disabled": true }
  }
}

You can also pass configuration options to individual servers:

{
  "lsp": {
    "python": {
      "settings": {
        "python": {
          "analysis": {
            "typeCheckingMode": "strict",
            "autoImportCompletions": true
          }
        }
      }
    },
    "rust-analyzer": {
      "settings": {
        "rust-analyzer": {
          "checkOnSave": true,
          "inlayHints": { "typeHints": true }
        }
      }
    }
  }
}

Server-specific settings use the same format as VS Code's LSP configuration blocks.

Experimental LSP Tool

opencode includes an experimental feature that exposes LSP operations as tool calls the model can invoke directly.

Enabling

Set the environment variable:

export OPENCODE_EXPERIMENTAL_LSP_TOOL=true

Supported Operations

When the experimental LSP tool is active, the model can invoke these operations:

Operation	Description
goToDefinition	Navigate to the definition of a symbol
findReferences	Find all references to a symbol
hover	Show hover information for a symbol
documentSymbol	List all symbols in the current document
workspaceSymbol	Search for symbols across the workspace
goToImplementation	Navigate to implementations of an interface or type
prepareCallHierarchy	Prepare call hierarchy data for a symbol
incomingCalls	Show calls that invoke the given symbol
outgoingCalls	Show calls the given symbol makes

Usage Example

Once enabled, the model can request LSP information during a conversation. For example, when you ask "What does this function do?", the model may invoke the hover operation against the symbol at the cursor position.

How LSP Works in opencode

opcode manages LSP servers per-workspace:

1. When a workspace is opened, opencode detects the project languages.
2. For each language with a known server, opencode downloads (if needed) and starts the LSP server process.
3. The server is kept alive for the duration of the session.
4. When LSP data is needed (e.g., for context in a prompt), opencode queries the appropriate server.
5. Servers are shut down when the session ends or the workspace is closed.

LSP servers communicate over stdio using the JSON-RPC protocol. opencode handles initialization, document synchronization, and shutdown automatically.

Performance Considerations

• LSP server startup can take a few seconds, especially for large projects.
• Each running server consumes memory. On resource-constrained systems, consider disabling unnecessary servers.
• For monorepos, LSP servers may index the entire repository. Use server-specific settings to exclude directories:

{
  "lsp": {
    "typescript": {
      "settings": {
        "typescript": {
          "exclude": ["node_modules", "dist", "build"]
        }
      }
    }
  }
}

Troubleshooting

Server Fails to Start

If a language server does not start:

• Verify the required runtime is installed (e.g., Node.js for TypeScript, JDK for Java).
• Check the server logs:

opencode debug lsp

• Try starting the server manually to verify it works:

typescript-language-server --stdio

LSP Tool Returns No Results

If the experimental LSP tool returns empty results:

• Confirm the document is saved and the language server has finished indexing.
• Check that the symbol exists in the current workspace.
• Verify the OPENCODE_EXPERIMENTAL_LSP_TOOL=true environment variable is set.

Slow Performance

If LSP operations are slow:

• Disable servers for languages you do not use.
• Reduce the workspace scope by opening only relevant directories.
• Increase server initialization timeout if needed:

{
  "lsp": {
    "initializeTimeoutMs": 30000
  }
}

Security Considerations

• Language servers execute arbitrary code on your machine. Only use trusted servers from official sources.
• The experimental LSP tool exposes file system information to the model — be mindful of sensitive code.
• Disable LSP entirely when working with untrusted code:

{
  "lsp": false
}