If you want to build your own IDE/Editor integration using the LSP protocol, or use OdooLS in a custom tool, this page walks you through what you need to know.

If you run into any issues, feel free to open an issue.

Prerequisites

OdooLS implements the Language Server Protocol (LSP). This page only covers what's specific to OdooLS — for the protocol itself, refer to the LSP specification.

Under the hood, the server is built in Rust using lsp-server (a minimal JSON-RPC library from rust-analyzer) for protocol handling, and lsp-types for LSP type definitions. Request dispatching and threading are handled by custom logic on top of these crates.

Configuration

The server pulls client configuration using the standard workspace/configuration request.

It will ask for the ConfigurationItem:

ConfigurationItem(
  scopeUri=None,
  section="Odoo",
)

The configuration response should include:

Setting	Description
selectedProfile	Name of the profile the user wants to use from the odools.toml file. If not provided (or empty), the server falls back to default. The special value Disabled tells the server to skip loading entirely.

Your client should give users a way to set this value — for example, a dropdown or input field. Without it, users won't be able to switch profiles or disable the server. If you implement the $Odoo/setConfiguration message (see below), the server will send you the list of available profiles to populate that UI.

Alternatively, if your client manages the server process directly, you can pass the --selected-config CLI argument when launching the server binary. This takes precedence over whatever the client sends via workspace/configuration.

Most other settings live in the odools.toml file — see the configuration files page for all available options.

Optional client-side settings (VSCode)

These settings are currently implemented in VSCode and control how the client manages the server, but don't communicate with the server itself. You can optionally implement them in your client if you manage the server process:

Setting	Description
serverConfigPath	Path to a custom odools.toml file. Your client can use this to pass --config-path when launching the server.
serverLogLevel	Server log level (one of: "trace", "debug", "info", "warn", "error"). Your client can pass this as --log-level when launching the server.

These are purely client-side conveniences — the server doesn't see them. Only implement them if your integration starts and configures the server process directly.

Custom messages

OdooLS works as a standard LSP server, so a basic integration should work out of the box. But you can handle some custom messages to improve the user experience.

Messages prefixed with $ are optional — your client doesn't have to implement them, but they help provide a smoother experience.

$Odoo/setPid

• Direction: Server → Client
• Type: Notification
• Parameters:
  • server_pid (int): The server's process ID.
• Description: Sent once at startup so you can track the server process if needed.

$Odoo/loadingStatusUpdate

• Direction: Server → Client
• Type: Notification
• Parameters:
  • status (string): Either "start" or "stop".
• Description: Tells you when the server is loading. Useful for showing a spinner or progress indicator.

Odoo/displayCrashNotification

• Direction: Server → Client
• Type: Notification
• Parameters:
  • crashInfo (string): The crash traceback.
  • pid (int): Process ID — can be used to find the related log file.
• Description: Sent when the server encounters a crash. Display this to the user so they can report it.

Note: This message does not have the $ prefix, unlike the other custom messages.

$Odoo/setConfiguration

• Direction: Server → Client
• Type: Notification
• Parameters:
  • html (dict): HTML representations of each profile, keyed by profile name. You can display these to let the user preview their configuration.
  • configFile (array): Serialized configuration profiles. See the configuration files page for the schema.
• Description: Sends all available profiles to your client. The user can then pick one by updating the selectedProfile setting in the "Odoo" section.

$Odoo/restartNeeded

• Direction: Server → Client
• Type: Notification
• Description: The server is asking you to restart it. When you receive this, trigger a proper restart sequence from the client side.

$Odoo/invalid_python_path

• Direction: Server → Client
• Type: Notification
• Description: The Python path configured in the current profile is invalid or couldn't be found. You should notify the user to check their configuration.