> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LSP Diagnostics

> Run a language server over a file and surface the compiler's errors/warnings via /lsp — no SDKs, speaking JSON-RPC with Content-Length framing.

The **`/lsp <file>`** command pulls the real diagnostics for a code file — the same errors and warnings your editor would show — by starting the appropriate **language server** and speaking the **Language Server Protocol** with it.

<Info>
  It's a **manual, per-file** command: you pass a file, ChatCLI starts the language server for its language, opens the document, waits for diagnostics and prints them. There is no automatic injection into `/agent`/`/coder`.
</Info>

***

## How it works

```text theme={"system"}
/lsp ./cli/agent_mode.go
     │
     ▼
detect language by extension (.go → gopls)
     │
     ▼
start the language server (stdio, JSON-RPC with Content-Length framing)
     │
     ▼
initialize → didOpen(file) → wait for publishDiagnostics (up to 12s)
     │
     ▼
print errors/warnings (or "No problems found")
```

1. **Language detection** — by file extension.
2. **Spawn** — starts the language's server (default command or your override). If the binary isn't installed/on `PATH`, `/lsp` says so.
3. **Handshake** — `initialize` + `textDocument/didOpen`.
4. **Diagnostics** — waits up to **12s** for `textDocument/publishDiagnostics` and renders the result.

***

## Languages and default commands

Each language uses a conventional stdio command, overridable via an environment variable. The binary must be installed and on `PATH`.

| Extensions                | Language server (default)            | Override                 |
| ------------------------- | ------------------------------------ | ------------------------ |
| `.go`                     | `gopls`                              | `CHATCLI_LSP_GO_CMD`     |
| `.py`                     | `pyright-langserver --stdio`         | `CHATCLI_LSP_PYTHON_CMD` |
| `.ts` `.tsx` `.js` `.jsx` | `typescript-language-server --stdio` | `CHATCLI_LSP_TS_CMD`     |
| `.rs`                     | `rust-analyzer`                      | `CHATCLI_LSP_RUST_CMD`   |
| `.c` `.h`                 | `clangd`                             | `CHATCLI_LSP_C_CMD`      |
| `.cpp` `.cc`              | `clangd`                             | `CHATCLI_LSP_CPP_CMD`    |
| `.java`                   | `jdtls`                              | `CHATCLI_LSP_JAVA_CMD`   |
| `.rb`                     | `solargraph stdio`                   | `CHATCLI_LSP_RUBY_CMD`   |

```bash theme={"system"}
# Example: enable gopls trace or point at a different binary
export CHATCLI_LSP_GO_CMD="gopls -rpc.trace"
export CHATCLI_LSP_PYTHON_CMD="pyright-langserver --stdio"
```

***

## Usage

```text theme={"system"}
> /lsp ./cli/agent_mode.go
  Starting language server: gopls...

  Diagnostics for agent_mode.go
  ─────────────────────────────────────────
  No problems found.
```

```text theme={"system"}
> /lsp ./broken.go
  Starting language server: gopls...

  Diagnostics for broken.go
  ─────────────────────────────────────────
  error  12:6   undefined: fmt.Printline
  warn   30:2   declared and not used: x
```

<Tip>
  Pair it with `/coder`: run `/lsp` on a file you just edited to confirm you didn't introduce compile errors before moving on.
</Tip>

***

## The @lsp tool — semantic navigation for the agent

The same LSP engine is also available to the **model** in agent and coder modes as the **`@lsp`** builtin tool — backed by a **session-scoped server pool** (the server initializes once per project and is reused across calls; idle servers shut down after 5 minutes):

| Subcommand                                | What it does                                     |
| ----------------------------------------- | ------------------------------------------------ |
| `diagnostics {file}`                      | compiler errors/warnings without running a build |
| `definition {file, line, column}`         | where the symbol is defined                      |
| `references {file, line, column, limit?}` | every usage of the symbol across the project     |
| `symbols {file}`                          | file outline: functions, types, methods          |
| `hover {file, line, column}`              | the symbol's signature/type/docs                 |

Positions are 1-based both ways. Where `@search` finds text, `@lsp` understands code: after editing a file, `diagnostics` confirms it still compiles; before changing a symbol, `references` shows the blast radius.

## See also

* [Coder Mode](/core-concepts/coder-mode)
* [Environment Variables → LSP](/reference/environment-variables#lsp-language-server-protocol-diagnostics)