Maple Harness home

Maple Harness 2.6.2 released! What's new in 2.6.2

Single userTeams & hubs

One person, one machine: the agent, the proxy and your own usage.

Several people, from one shared proxy up to a hub of hubs.

Language servers #

On this page
  1. In plain words
  2. How it finds servers
  3. Check what it found
  4. Install a server
  5. Gherkin and Cucumber
  6. Choose the servers yourself
  7. Turn it off
  8. When the agent still writes files with echo and cat
  9. Troubleshooting
  10. What has been tried
  11. Related

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) and lsp_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 /lsp in 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.

LanguageMarker files in the project folderServerInstall
Gogo.mod, go.workgoplsgo install golang.org/x/tools/gopls@latest
TypeScript, JavaScripttsconfig.json, jsconfig.json, package.jsontypescript-language-servernpm i -g typescript typescript-language-server
Pythonpyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfilepyright-langserver (or pylsp)pip install pyright, or npm i -g pyright; for pylsp: pip install python-lsp-server
RustCargo.tomlrust-analyzerrustup component add rust-analyzer
C, C++compile_commands.json, CMakeLists.txt, .clangdclangdmacOS: 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
Javapom.xml, build.gradle, build.gradle.ktsjdtlsInstall the Eclipse JDT Language Server and put jdtls on your PATH
SwiftPackage.swiftsourcekit-lspComes with the Swift toolchain (on macOS, Xcode or xcode-select --install)
RubyGemfile, .ruby-versionruby-lsp (or solargraph)gem install ruby-lsp
PHPcomposer.jsonintelephense (or phpactor)npm i -g intelephense
Lua.luarc.json, .luacheckrc, init.lualua-language-serverInstall lua-language-server from your package manager
Shellany *.sh in the folder or in scripts/bash-language-servernpm 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 filecucumber-language-servernpm 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 /lsp says missing. The agent looks on the PATH it was started with. A tool installed by npm i -g or go install lives in a folder that must be on that PATH (for Go, ~/go/bin). Start the agent from a shell where the command works, and check with which 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. /lsp must 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 .feature file 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.

The settings are in Harness settings, and /lsp is in Commands and keys. Other problems: Troubleshooting.

Made with ❤️ by Kinn Coelho Juliao in Ottawa, eh — fuelled by double-doubles, bud. 🍁