Language servers and formatters

o4 can connect to language servers and code formatters you already have installed. With a language server, the model can jump to definitions, find references, and read type information instead of searching text. With a formatter, the model can format a file after it edits it. Both are tools the model calls when it decides to. o4 doesn’t run them automatically after each edit, and it doesn’t feed language-server diagnostics back to the model. Both are available in interactive sessions, not in print mode (o4 -p) or evals.

Language servers

Language servers work without setup for four languages, as long as the server is installed and on your PATH:

Server command	File extensions
`rust-analyzer`	`.rs`
`typescript-language-server --stdio`	`.ts`, `.tsx`, `.js`, `.jsx`
`pyright-langserver --stdio`	`.py`
`gopls`	`.go`

o4 starts a server the first time the model asks about a file with one of its extensions, and keeps it running for the rest of the session. It starts a separate copy of the server for each extension, so .ts and .tsx files get two typescript-language-server processes. The server runs in the directory you started o4 in. If a server isn’t installed, the model’s request fails with an error and the session carries on.

In 0.2.74, o4 doesn’t send language servers the initialize request that the language server protocol requires before anything else. Standard servers such as rust-analyzer and clangd answer every request with a “not initialized” error, so the lsp tool returns an LSP error -32002 instead of a result. For code navigation that works today, use the code index. See Code intelligence.

What the model can do

The model uses the lsp tool, which takes an operation, a file path (filePath), and a 1-based line and character position:

Operation	What it returns
`goToDefinition`	Where the symbol at the position is defined
`findReferences`	Every place the symbol is used
`hover`	Type and documentation for the symbol
`documentSymbol`	The symbols in the file
`workspaceSymbol`	Symbols across the workspace. The tool always sends an empty search query.
`goToImplementation`	Implementations of an interface or trait
`prepareCallHierarchy`	The call-hierarchy item at the position
`incomingCalls`	Callers of the function
`outgoingCalls`	Functions it calls

incomingCalls and outgoingCalls send a file position, but the protocol expects the item that prepareCallHierarchy returns, so servers can reject them. In the default ask permission mode, the first lsp call in a session asks for your approval. After you approve, o4 doesn’t ask again for the rest of the session. See Permissions. For text and symbol search that doesn’t need a language server, see Code intelligence.

Configure language servers

To use other servers, or change the command for a built-in one, add lsp_servers to ~/.o4/settings.json. Each entry has a name you choose, the command, optional arguments, and the file extensions it handles (without the dot):

{
  "lsp_servers": {
    "rust": {
      "command": "rust-analyzer",
      "extensions": ["rs"]
    },
    "clangd": {
      "command": "clangd",
      "args": ["--background-index"],
      "extensions": ["c", "h", "cpp", "hpp"]
    }
  }
}

Once lsp_servers has at least one entry, it replaces the built-in list. List every server you want, including any of the four built-in ones.

An entry needs a non-empty command and at least one extension. o4 ignores entries without them. Extensions match without regard to case, and an extension written with a leading dot, such as ".rs", never matches. If two entries claim the same extension, the entry whose name sorts first alphabetically wins. If every entry is invalid, the model gets no working servers; o4 doesn’t fall back to the built-in list. o4 reads these settings when it starts. Restart o4 after you change them.

Formatters

o4 has no built-in formatters. When you configure at least one, the model gets a format tool that formats one file at a time with the formatter set for that file’s extension. Add formatters to ~/.o4/settings.json:

{
  "formatters": {
    "rustfmt": {
      "command": "rustfmt",
      "args": ["--edition", "2021"],
      "extensions": ["rs"]
    },
    "prettier": {
      "command": "prettier",
      "args": ["--write"],
      "extensions": ["ts", "tsx", "js", "json", "md"]
    }
  }
}

o4 runs the command with your args and then the file path, so the formatter must rewrite the file in place. That’s why the prettier example passes --write. Like language servers, an entry needs a non-empty command and at least one extension, and when two entries claim the same extension, the name that sorts first wins. How a formatter runs:

The file must already exist inside the folders o4 may access, and the tool formats one file per call.
It runs through the same sandbox as the model’s shell commands. See Sandbox.
It has 2 minutes to finish unless the model sets a shorter or longer timeout, in milliseconds.
If it exits with a non-zero code, the model gets the formatter’s output as the error. On success the model gets Formatted <file> with <name>, not the formatter’s output.
In the default ask permission mode, the first format call in a session asks for your approval. After you approve, o4 doesn’t ask again for the rest of the session.

o4 reads these settings when it starts. Restart o4 after you change them.

Project settings

You can also put lsp_servers and formatters in .o4/settings.json in a project, so everyone who works on it gets the same setup. o4 reads that file from the directory you start o4 in. Project entries are added to your user entries, and a project entry replaces a user entry with the same name. A project lsp_servers entry also replaces the built-in list, as it does in your own file. Because these settings choose programs to run, o4 reads a project’s .o4/settings.json only after you trust the workspace. See Workspace trust.

See your setup

Run /config tools to open the Tools tab of the settings. It lists the language servers and formatters o4 will use:

LSP servers shows each configured server as name: command args [extensions], or the four built-in server commands when you haven’t configured any.
Formatters shows each configured formatter the same way, or not configured.

Each row lists the first three entries by name, then +N more, and N invalid for entries o4 ignores because they have no command or no extensions. Press Enter on a row to see the full value. The rows are read-only. Edit settings.json to change them. See Configuration files for where settings live.

Get started

Using o4

Planning and agents

Models

Safety

Customize

Extend

Help

Language servers and formatters