Language servers

Use a language server to check files for errors and warnings while you work with Orek. The Language Server Protocol (LSP) is the protocol editors use to communicate with these servers.

Orek only reads diagnostics from the server and keeps it up to date with your files; it refuses any request from the server to edit files. A trusted server can still run compilers, build scripts, procedural macros, and other project code, so review the server and project before granting access.

Before you begin

You need an installed Orek release, a project, and the language server’s executable. Install the server yourself and make its command available on PATH, or configure its path explicitly. Orek does not install language servers.

The example below uses a Rust project and rust-analyzer. Replace the server and file path for another language. LSP is off by default.

Configure and trust a server first, then check files from your shell (orek lsp check <file>) or by asking in chat. There is no /lsp check command inside Orek.

Enable a server

Add this to your project or user configuration:

[lsp]
enabled = true

[lsp.servers.rust-analyzer]
command = "rust-analyzer"
language_ids = ["rust"]
root_markers = ["Cargo.toml"]

After editing configuration, restart Orek in the project and check server status:

/lsp

/doctor

Enabling LSP does not grant permission to start the process. Preview the server’s configuration and the access it requests:

/lsp trust rust-analyzer

If the preview matches the server and project you intend to use, grant consent:

/lsp trust rust-analyzer confirm

The grant is stored in your user data directory, not in the project. It stops applying if the project root, the server’s configuration or its executable changes, or, on macOS, the /sandbox setting. Adding or removing a server entry does not grant consent.

Read diagnostics

Check a file from your terminal. This example assumes your Rust project has a src/lib.rs file:

orek lsp check "src/lib.rs"

Read both the diagnostics and the reported state. An unavailable, starting, untrusted, timed-out, or crashed language server has not verified the file and is never reported as a clean file.

In the TUI, /lsp provides status, trust, revoke, reset, and restart controls. You can also ask the agent to check a file; it uses its lsp_diagnostics tool, which also works in Plan mode.

Optional automatic diagnostics

Orek can add diagnostics to the result of each successful edit, and to the content of an @file reference before the next model request.

Both options are off by default. The added diagnostics are not saved in the session history. Turn them on only if the results are worth the extra wait and token cost. See the LSP configuration reference.

Troubleshooting

To withdraw one grant, use orek lsp revoke <server>. To remove all grants, use orek lsp reset --confirm.

Server selection

Orek has built-in settings for 16 language servers. A built-in entry tells Orek how to run the server; it does not install it.

Built-in servers default to enabled = true and soft_fail = true, while the overall lsp.enabled switch defaults to false. A [lsp.servers.<name>] entry with a built-in name keeps every built-in field you do not set; set an empty list or table (args = [], language_id_map = {}) or an explicit value (priority = 0) to clear or override one.

A server’s platforms list limits the operating systems it can run on. An empty list allows all of them; the built-in sourcekit-lsp entry allows macOS and Linux.

Match files and workspace roots

A server handles a file that matches any of its filenames, extensions, or shebangs, or that has an extension Orek knows for one of its language_ids. Use language_id_map to change the language ID sent to the server for an extension:

[lsp.servers.clangd]
command = "clangd"
language_ids = ["c"]
extensions = ["c", "cpp"]
language_id_map = { cpp = "cpp" }

The workspace root is the folder that contains any root_markers entry, or all entries of one root_marker_groups list. Set root_strategy = "outermost" when a nested project needs the outer workspace instead of the default nearest root.

Process environment and platform limits

Server processes receive only a basic set of environment variables plus LC_* locale variables; provider API keys and RUSTUP_TOOLCHAIN are left out unless you list them in env. Updating the server executable on disk requires running /lsp trust <server> again.

On macOS, turning on the OS sandbox (/sandbox on, off by default) restarts running servers inside the macOS sandbox. Each trust grant applies to one sandbox setting, so run /lsp trust <server> again if a server has not been trusted under the current /sandbox mode. Review the security model before running a server in an untrusted project.

For all fields, see the LSP configuration reference.