Skip to content

LSP Servers

Lunos integrates with your LSP servers.

Lunos can integrate with Language Server Protocol (LSP) servers to use diagnostics as feedback for the agent.


Built-in

Lunos comes with several built-in LSP servers for popular languages:

LSP ServerExtensionsRequirements
astro.astroAuto-installs for Astro projects
bash.sh, .bash, .zsh, .kshAuto-installs bash-language-server
clangd.c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++Auto-installs for C/C++ projects
csharp.cs, .csx.NET SDK installed
clojure-lsp.clj, .cljs, .cljc, .ednclojure-lsp command available
dart.dartdart command available
deno.ts, .tsx, .js, .jsx, .mjsdeno command available (auto-detects deno.json/deno.jsonc)
elixir-ls.ex, .exselixir command available
eslint.ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vueeslint dependency in project
fsharp.fs, .fsi, .fsx, .fsscript.NET SDK installed
gleam.gleamgleam command available
gopls.gogo command available
hls.hs, .lhshaskell-language-server-wrapper command available
jdtls.javaJava SDK (version 21+) installed
julials.jljulia and LanguageServer.jl installed
kotlin-ls.kt, .ktsAuto-installs for Kotlin projects
lua-ls.luaAuto-installs for Lua projects
nixd.nixnixd command available
ocaml-lsp.ml, .mliocamllsp command available
oxlint.ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelteoxlint dependency in project
php intelephense.phpAuto-installs for PHP projects
prisma.prismaprisma command available
pyright.py, .pyipyright dependency installed
razor.razor, .cshtml.NET SDK and VS Code C# extension installed
ruby-lsp (rubocop).rb, .rake, .gemspec, .ruruby and gem commands available
rust.rsrust-analyzer command available
sourcekit-lsp.swift, .objc, .objcppswift installed (xcode on macOS)
svelte.svelteAuto-installs for Svelte projects
terraform.tf, .tfvarsAuto-installs from GitHub releases
tinymist.typ, .typcAuto-installs from GitHub releases
typescript.ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .ctstypescript dependency in project
vue.vueAuto-installs for Vue projects
yaml-ls.yaml, .ymlAuto-installs Red Hat yaml-language-server
zls.zig, .zonzig command available

LSP is enabled by default. Servers start when one of the above file extensions is detected and the requirements are met. A server already installed on your machine, in the project’s node_modules/.bin or on your PATH, is used first; otherwise it’s downloaded the first time a matching file is opened.


How It Works

When LSP is enabled and Lunos opens a file, it:

  1. Checks the file extension against all enabled LSP servers.
  2. Starts the appropriate LSP server if not already running.

Seeing what’s running

/lsp (also /settings → Tools → lsp) shows whether LSP is on, whether downloads are allowed, and every server with its state. lunos lsp status [--json] prints the same list; add --file <path> to open a file first, so its servers start and you see how that went.

StateMeaning
RunningStarted for a file the agent read; shows where the binary came from, the project root and PID.
Starting…Starting now.
FailedDidn’t start, with the reason (see below). It’s retried after Restart or in a new session.
Not startedNo matching file has been read yet.
OffLSP is off ("lsp": false), or this server is turned off (lsp.<id>.disabled).

Enter on a server: Restart, Stop, Turn off / on (writes lsp.<id>.disabled to your user config), and View log (its stderr this session). The sidebar shows a failed server with its reason.

Troubleshooting

  • command not found: … — the binary isn’t on PATH or in the project’s node_modules/.bin. Install it, or set command for that server.
  • not installed, and downloads are off — OPENCODE_DISABLE_LSP_DOWNLOAD (or offline mode) is set, so Lunos won’t fetch it. Install it yourself, or allow downloads.
  • not found here, and not downloaded — some servers need the project to have a dependency first (typescript for the TypeScript server).
  • exited with code N before it finished starting — the server started and quit; the last lines of its stderr follow. Often a missing project config (a biome.json, for example). View log shows everything it wrote.

Best Practices

LSP can help the agent find and fix issues by providing diagnostics from language servers. This is useful in some projects, but it is not always a net positive.

Language servers can get out of sync, use significant memory, vary by version or project, and slow down agent workflows. In some projects it is better to have the agent run lint, typecheck, or other diagnostic CLI tools directly, so errors are fed back into the agent loop without those tradeoffs. Document those commands in instruction files such as AGENTS.md or skills so the agent knows what to run, and set lsp to false (or disable specific servers) when language-server feedback doesn’t help your project.


Configure

You can enable and customize LSP servers through the lsp section in your Lunos config.

To enable all built-in LSP servers, set lsp to true.

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": true
}

Use an object to keep built-ins enabled while configuring overrides or custom servers.

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": {}
}

Each configured LSP server entry supports the following:

Server entries need command unless they only disable a server.

PropertyTypeDescription
disabledbooleanSet this to true to disable the LSP server
commandstring[]The command to start the LSP server
extensionsstring[]File extensions this LSP server should handle
envobjectEnvironment variables to set when starting server
initializationobjectInitialization options to send to the LSP server

Let’s look at some examples.


Environment variables

Use the env property to set environment variables when starting the LSP server:

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": {
"rust": {
"command": ["rust-analyzer"],
"env": {
"RUST_LOG": "debug"
}
}
}
}

Initialization options

Use the initialization property to pass initialization options to the LSP server. These are server-specific settings sent during the LSP initialize request:

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": {
"custom-lsp": {
"command": ["custom-lsp-server", "--stdio"],
"extensions": [".custom"],
"initialization": {
"preferences": {
"importModuleSpecifierPreference": "relative"
}
}
}
}
}

Disabling LSP servers

If lsp is omitted, the built-in LSP servers are enabled. To disable all LSP servers, set lsp to false:

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": false
}

To disable a specific LSP server, set disabled to true:

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": {
"typescript": {
"disabled": true
}
}
}

Custom LSP servers

You can add custom LSP servers by specifying the command and file extensions:

opencode.json
{
"$schema": "https://lunos.tech/config.json",
"lsp": {
"custom-lsp": {
"command": ["custom-lsp-server", "--stdio"],
"extensions": [".custom"]
}
}
}

Additional Information

PHP Intelephense

PHP Intelephense offers premium features through a license key. You can provide a license key by placing (only) the key in a text file at:

  • On macOS/Linux: $HOME/intelephense/license.txt
  • On Windows: %USERPROFILE%/intelephense/license.txt

The file should contain only the license key with no additional content.