Hermes LSP Diagnostics — Code Checked as You Type

Think of a spell-checker for your writing, but for code — that’s LSP Diagnostics.

What Is an LSP, Anyway?

LSP stands for Language Server Protocol. It’s a behind-the-scenes helper that your code editor talks to. When you type, the editor sends your code to the language server, which checks for mistakes and sends back suggestions. You see the result as red squiggly underlines, yellow warnings, or little lightbulb icons.

In Hermes Agent, we use LSP to give you instant feedback while you write — no need to run a separate “check” command. It’s like having a patient senior developer peeking over your shoulder, pointing out typos and logic slips before you even save the file.

Why Should Beginners Care?

You don’t need to know how LSP works internally. But you do need to know that:

• It catches simple mistakes (missing brackets, wrong variable names) immediately.
• It teaches you as you go — hover over a squiggle to see the problem and a fix.
• It saves time — you fix issues while they’re fresh, not after a long debugging session.

How to Use LSP Diagnostics in Hermes Agent

Hermes Agent comes with LSP support built in. Here’s how to get started:

1. Open Your Project

Make sure you’re in the folder with your code. In your terminal:

cd my-project

2. Check That a Server Is Ready

Run this command to see the service state and which language servers are installed:

hermes lsp status

If a server you need is missing, install it with hermes lsp install <id>, or try every server with a known recipe via hermes lsp install-all. You can also list the registry with hermes lsp list (add --installed-only to narrow it down) and print a resolved binary path with hermes lsp which <id>.

3. Read the Diagnostic Panel

In most editors, press:

Ctrl+Shift+M   (Windows/Linux)
Cmd+Shift+M    (Mac)

This opens the “Problems” panel. It lists every issue, with the file name, line number, and a short description.

4. Apply Quick Fixes

Click on a squiggly line. A small popup will appear. Choose “Quick Fix” or press:

Ctrl+.   (Windows/Linux)
Cmd+.    (Mac)

Hermes Agent will suggest a fix — often just one keystroke to accept it.

What Do the Symbols Mean?

• Red underline = error. Something is definitely wrong (e.g., undefined function).
• Yellow underline = warning. Not fatal, but likely a bug (e.g., unused variable).
• Blue/lightbulb = suggestion. Optional improvement (e.g., simplify this code).

A Real Example

Let’s say you type this in Python:

def greet(name):
    print("Hello, " + nam)

Notice the nam — a typo. The LSP will underline it in red. Hover over it, and you’ll see:

Name "nam" is not defined. Did you mean "name"?

Click the quick fix, and it changes to name automatically. You just avoided a crash.

Workspace Trust: Why Some Servers Stay Quiet

Many language servers run code that a project ships — for example, rust-analyzer runs cargo check on every save, and typescript-language-server loads the project’s own node_modules/typescript. That’s fine for your own project, but not for a repository the agent just cloned.

So Hermes treats every workspace as untrusted unless it is:

• the git worktree of a directory you pointed Hermes at (where you launched it with cd my-app && hermes, the worktree hermes -w created, the project a Desktop or TUI session is opened in, or a gateway’s terminal.cwd), or
• a directory listed under lsp.trusted_workspaces (or any directory below one).

A cd in the agent’s terminal does not move the session’s workspace. Cron jobs and Kanban workers get no automatic trust, because the agent can choose their workdir or workspace; list the directories they should trust under lsp.trusted_workspaces. A checkout nested inside a trusted worktree has its own .git, so it is not trusted, and neither is a git repository at or above your home directory (a dotfiles repo there would otherwise trust everything below it). Trust covers the whole directory you pointed Hermes at, including anything later cloned into it, and lasts until Hermes exits.

In an untrusted workspace Hermes denies by default: only a small set of servers start, each with settings that keep it on Hermes-side tools. Every other server is skipped, including rust-analyzer, gopls, jdtls, kotlin-language-server, elixir-ls, zls, clojure-lsp, haskell-language-server, lua-language-server, terraform-ls, prisma, astro, vue-language-server (it loads the vueCompilerOptions.plugins a project’s tsconfig.json names) and any server you declare under lsp.servers. The diagnostics log records skipped: untrusted workspace …; add it to lsp.trusted_workspaces, and hermes lsp status marks those servers [trusted workspaces only].

To trust a project, add it to your config:

lsp:
  trusted_workspaces:
    - ~/code/my-app

On a local backend, the post-write shell linters that would use the checkout’s own toolchain are skipped the same way whenever the terminal’s current directory is untrusted: npx tsc (it runs the repository’s node_modules/.bin/tsc, or installs from the registry its .npmrc names) and rustfmt --check (rustup honours the repository’s rust-toolchain.toml). Sandboxed backends (Docker, SSH, Modal, …) are unchanged.

Diagnostics that need the project’s dependencies (for example unresolved-import warnings) may be less precise until you trust the workspace.

Tuning the Wait Budget

After a successful write_file or patch, Hermes sends the new content to the language server and waits for the verdict only while the whole tool call stays under about 80 ms. TypeScript (typescript-language-server) answers a synchronous diagnostics request, and pyright answers a document pull; warm servers usually reply in 10–90 ms. When the verdict has diagnostics, Hermes compares them against the verdict on the pre-edit content and keeps only the new ones. A verdict that arrives inside that window appears in the tool result’s lsp_diagnostics; a slower one (cold server, very large file) is attached to the session’s next tool result, labelled LSP diagnostics introduced by your earlier edit of <path>. If the model tries to finish the turn while a check is still running, Hermes waits up to 5 s for it, and any problems go to the model as a new message before the answer is accepted — so a one-shot hermes chat -q run still sees them. Earlier messages are never rewritten. If the same file is edited again before its check finishes, the newer check runs against the older edit’s baseline, so errors the first edit introduced are still reported unless the second edit fixed them. Raise lsp.wait_timeout for slow servers on big projects.

The very first request against a workspace also pays the spawn, initialize and the server’s initial program build (tsserver on a 10k-file project can need a minute), so give large projects room with lsp.warmup_timeout (only that first, cold request uses it — the steady-state budget is unchanged; 0 means no extra grace, same as wait_timeout) rather than raising wait_timeout. If a server fails for a workspace, that (server, root) pair is skipped; set lsp.broken_retry_seconds to retry it after N seconds instead of for the rest of the process. And if one huge monorepo can’t finish in budget, list it under lsp.exclude_roots so every other workspace keeps its diagnostics.

Common Pitfalls (And How to Avoid Them)

• Don’t ignore warnings — they often point to future bugs.
• Check the panel regularly — not just the current line.
• If you see “No LSP server found” — make sure your file type is supported. You can check what’s ready with hermes lsp status, and install a missing server with hermes lsp install <id>. If a client is stuck, hermes lsp restart tears down running clients.
• If a server shows [trusted workspaces only] — you’re in an untrusted workspace. Add the directory to lsp.trusted_workspaces and restart Hermes.

Summary and Practical Tip

LSP Diagnostics give you real-time feedback, making coding feel more like a conversation than a guessing game. You write, the tool nudges, you fix — it’s that simple.

Practical tip: Before you run your code, always glance at the Problems panel. One quick look can save you ten minutes of “Why is this broken?” debugging. Make it a habit — your future self will thank you.

Now go write some code, and let the squiggles guide you.