Language servers #
On this page
Language servers give the agent compile errors right after every edit. A language server is the program your editor uses to underline errors, jump to a definition and show a type on hover, and Maple Harness can use the same programs. With one installed for your project's language:
- Errors are shown right after each edit. When the agent writes or edits a file, the errors the language server finds in it are added to the tool's result, so the agent sees a compile or type error straight away and fixes its own mistake on the next step instead of finding out when the build fails.
- The agent can look things up. Three tools become available:
lsp_diagnostics(the errors and warnings for a file),lsp_definition(where a symbol is defined) andlsp_hover(its type and documentation).
Nothing is installed for you, and nothing runs until it is useful: a server starts the first time a file of its type is edited or looked up.
In plain words #
- What it is. The programs your editor uses to underline errors. The agent uses the same ones.
- Why you want it. The agent sees a compile error right after its edit and fixes it on the next step, instead of finding out when the build fails.
- What to do. Have the language server for your language installed (the one your editor uses). Type
/lspin a session to see what was found; it prints the install command for anything missing.
How it finds servers #
By default (harness.lsp: auto), the agent looks at the folder you started it in. If it finds a file that marks a
language, and the matching server is on your PATH, that server is used for that language. Nothing else is
needed.
If you name servers yourself in harness.lsp_servers, those are used exactly as you wrote them and nothing is
detected.
Check what it found #
Type /lsp in a session. It lists each server as running, idle (installed, starts when first needed) or
missing, and prints the install command for a missing one.
Language servers (detected from this project and your PATH):
Go gopls idle
TypeScript/JavaScript typescript-language-server missing
install: npm i -g typescript-language-server typescript
maple-harness doctor has a "Language servers" line too. A missing server is only a warning: everything still
works, the agent just doesn't get compile errors back after an edit.
Install a server #
Start the agent in the project's root folder, the one with the marker file. The first two columns say what triggers a language and which server is used.
| Language | Marker files in the project folder | Server | Install |
|---|---|---|---|
| Go | go.mod, go.work | gopls | go install golang.org/x/tools/gopls@latest |
| TypeScript, JavaScript | tsconfig.json, jsconfig.json, package.json | typescript-language-server | npm i -g typescript typescript-language-server |
| Python | pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile | pyright-langserver (or pylsp) | pip install pyright, or npm i -g pyright; for pylsp: pip install python-lsp-server |
| Rust | Cargo.toml | rust-analyzer | rustup component add rust-analyzer |
| C, C++ | compile_commands.json, CMakeLists.txt, .clangd | clangd | macOS: xcode-select --install or brew install llvm. Debian/Ubuntu: sudo apt install clangd. Arch: sudo pacman -S clang. Fedora: sudo dnf install clang-tools-extra |
| Java | pom.xml, build.gradle, build.gradle.kts | jdtls | Install the Eclipse JDT Language Server and put jdtls on your PATH |
| Swift | Package.swift | sourcekit-lsp | Comes with the Swift toolchain (on macOS, Xcode or xcode-select --install) |
| Ruby | Gemfile, .ruby-version | ruby-lsp (or solargraph) | gem install ruby-lsp |
| PHP | composer.json | intelephense (or phpactor) | npm i -g intelephense |
| Lua | .luarc.json, .luacheckrc, init.lua | lua-language-server | Install lua-language-server from your package manager |
| Shell | any *.sh in the folder or in scripts/ | bash-language-server | npm i -g bash-language-server |
| Gherkin (Cucumber) | a features/ folder, any *.feature file near the top of the project, or a cucumber.js/cucumber.json/cucumber.yaml file | cucumber-language-server | npm i -g @cucumber/language-server |
Package names for the C and C++ server differ by distribution; the ones above are the usual ones. The other installers are each language's own.
After installing, open /lsp again, or restart the agent, so it sees the new program on your PATH.
Gherkin and Cucumber #
If your project describes behaviour in .feature files (behaviour-driven development), the Cucumber language
server checks them. The most useful thing it does is report a step with no matching step definition, so when
the agent writes a scenario, it learns immediately which steps still need code.
A typical project:
features/
export.feature
steps/
export.steps.js
Feature: Export
Scenario: Export as JSON
Given the app is loaded
When I export the expenses as JSON
When the agent writes features/export.feature, the result of that write includes something like:
Language-server diagnostics for features/export.feature (0 error(s), 1 warning(s)):
features/export.feature:4:10: warning: Undefined step: I export the expenses as JSON
and the agent writes the missing step definition next. The server looks for features and step definitions in the
usual places for Cucumber in JavaScript and TypeScript, Java, Ruby, Python, PHP, Rust, C# and Go (for example
features/**/*.feature with step code under features/, or src/test/** for Java). If your project keeps them
elsewhere, the defaults are used and steps in other folders will look undefined.
Choose the servers yourself #
Add lsp_servers to config.yaml. Each entry names the file extensions, the command and its arguments. This
replaces detection.
harness:
lsp_servers:
- {extensions: [".go"], command: gopls}
- {extensions: [".ts", ".tsx", ".js"], command: typescript-language-server, args: ["--stdio"]}
- {extensions: [".feature"], command: cucumber-language-server, args: ["--stdio"]}
Turn it off #
harness:
lsp: off
With lsp: off no server is started, no errors are added to results and the three lookup tools are not offered.
lsp: auto is the default.
When the agent still writes files with echo and cat #
The agent is told to create and change files with its own file tools, because those show you a diff, apply the
safety checks and run the language server. Some models still write files through the shell, for example with
cat > file <<EOF. By default the agent notes it in that command's result so the model can correct itself. You can
change this:
harness:
bash_file_writes: warn # the default: run it, and add a note
# bash_file_writes: deny # refuse it, and tell the model to use write_file or edit_file
# bash_file_writes: allow # say nothing
deny suits small models that keep doing it: the command is refused with a message naming the file, and the
model tries again with the right tool. Commands that only capture a program's output, such as npm test > out.txt,
are not affected.
Troubleshooting #
- Installed, but
/lspsays missing. The agent looks on thePATHit was started with. A tool installed bynpm i -gorgo installlives in a folder that must be on thatPATH(for Go,~/go/bin). Start the agent from a shell where the command works, and check withwhich gopls(or the server's name). - No server is listed at all. Start the agent in the project's root folder, the one with the marker file. In a larger repository with several projects, start it in the project you are working on.
- The first result has no errors, later ones do. A server indexes your project the first time it is used, and the first edit only starts it. Later edits get errors. Big projects can take some seconds.
- A server keeps failing. The agent stops restarting a server that keeps exiting and says what the server last printed. Run the server's command yourself in the project folder to see why it fails.
- No errors are shown for a file type.
/lspmust list a server whose extensions include that file type.
What has been tried #
Stated plainly, so you know what to expect:
- The way the agent starts servers, sends them each edit and reads back their errors, and the answers it gives to the requests servers make of an editor, has been tested against a stand-in server in the test suite.
- The Cucumber language server was run for real: it reported "Undefined step" warnings for a
.featurefile right after it was written. In that test the server could not load one of its own grammar files, so step definitions were not recognised and every step was reported as undefined; how well it matches your step definitions has not been checked. - Detection of every language in the table is tested with stand-in programs. The other servers have not been run against real projects here, and the install commands come from each project's own instructions.
Related #
The settings are in Harness settings, and /lsp is in
Commands and keys. Other problems: Troubleshooting.