> ## 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>
  `/lsp <file>` is the **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. Separately, the `@coder` engine now **automatically** checks the files it just edited — see [Automatic post-edit diagnostics](#automatic-post-edit-diagnostics) below.
</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>

***

## Automatic post-edit diagnostics

You no longer have to run `/lsp` by hand to catch a broken edit. In `/agent` and `/coder`, after a **successful** `@coder write`, `patch` or `multipatch`, the engine runs the language server over the files it just touched and appends any findings to the tool result as a compact **`[DIAGNOSTICS]`** block:

```text theme={"system"}
File written.

[DIAGNOSTICS] The edit succeeded but the language server reports issues in the touched file(s). Fix them before moving on:
2 diagnostic(s) in cli/agent_mode.go:
- L128:6 [error] undefined: fmt.Printline (compiler)
- L214:2 [warning] declared and not used: x
```

The model sees the problem **immediately** — the same turn as the edit — instead of turns later when a test fails. This is the single cheapest way to keep an agent's edits compiling.

Behavior and guardrails:

* **On by default**, toggled with `CHATCLI_CODER_AUTODIAG` (`off`/`false`/`no` to disable).
* **Silent on clean files** — a file with no diagnostics appends nothing, so the happy path costs zero tokens.
* **Bounded** — at most **5 files** per edit, a **3000-character** budget for the block, and a **wall-clock budget for the whole pass**; overflow and skipped files are elided with an explicit note.
* **Never blocks on a cold server** — if the session pool hasn't started a server for that language yet, the check reports nothing now, warms the server **in the background**, and the next edit gets real findings. Your write's result renders immediately either way.
* **Degrades to a no-op** when no language server is available for the file's language (or when running on a surface without the session LSP pool). It reuses the same session-scoped server pool as the `@lsp` tool below, so there's no extra startup cost.

<Tip>
  Keep it on: it turns "the build broke three steps ago" into "fix this line now", with no prompting discipline required from the model.
</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 15 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](/usage/coder-mode)
* [Environment Variables → LSP](/reference/environment-variables#lsp-language-server-protocol-diagnostics)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.