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 Server | Extensions | Requirements |
|---|---|---|
| astro | .astro | Auto-installs for Astro projects |
| bash | .sh, .bash, .zsh, .ksh | Auto-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, .edn | clojure-lsp command available |
| dart | .dart | dart command available |
| deno | .ts, .tsx, .js, .jsx, .mjs | deno command available (auto-detects deno.json/deno.jsonc) |
| elixir-ls | .ex, .exs | elixir command available |
| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | eslint dependency in project |
| fsharp | .fs, .fsi, .fsx, .fsscript | .NET SDK installed |
| gleam | .gleam | gleam command available |
| gopls | .go | go command available |
| hls | .hs, .lhs | haskell-language-server-wrapper command available |
| jdtls | .java | Java SDK (version 21+) installed |
| julials | .jl | julia and LanguageServer.jl installed |
| kotlin-ls | .kt, .kts | Auto-installs for Kotlin projects |
| lua-ls | .lua | Auto-installs for Lua projects |
| nixd | .nix | nixd command available |
| ocaml-lsp | .ml, .mli | ocamllsp command available |
| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | oxlint dependency in project |
| php intelephense | .php | Auto-installs for PHP projects |
| prisma | .prisma | prisma command available |
| pyright | .py, .pyi | pyright dependency installed |
| razor | .razor, .cshtml | .NET SDK and VS Code C# extension installed |
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | ruby and gem commands available |
| rust | .rs | rust-analyzer command available |
| sourcekit-lsp | .swift, .objc, .objcpp | swift installed (xcode on macOS) |
| svelte | .svelte | Auto-installs for Svelte projects |
| terraform | .tf, .tfvars | Auto-installs from GitHub releases |
| tinymist | .typ, .typc | Auto-installs from GitHub releases |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | typescript dependency in project |
| vue | .vue | Auto-installs for Vue projects |
| yaml-ls | .yaml, .yml | Auto-installs Red Hat yaml-language-server |
| zls | .zig, .zon | zig 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:
- Checks the file extension against all enabled LSP servers.
- 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.
| State | Meaning |
|---|---|
| Running | Started for a file the agent read; shows where the binary came from, the project root and PID. |
| Starting… | Starting now. |
| Failed | Didn’t start, with the reason (see below). It’s retried after Restart or in a new session. |
| Not started | No matching file has been read yet. |
| Off | LSP 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
PATHor in the project’snode_modules/.bin. Install it, or setcommandfor 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 (
typescriptfor 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.
{ "$schema": "https://lunos.tech/config.json", "lsp": true}Use an object to keep built-ins enabled while configuring overrides or custom servers.
{ "$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.
| Property | Type | Description |
|---|---|---|
disabled | boolean | Set this to true to disable the LSP server |
command | string[] | The command to start the LSP server |
extensions | string[] | File extensions this LSP server should handle |
env | object | Environment variables to set when starting server |
initialization | object | Initialization 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:
{ "$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:
{ "$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:
{ "$schema": "https://lunos.tech/config.json", "lsp": false}To disable a specific LSP server, set disabled to true:
{ "$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:
{ "$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.