LSP Semantic Diagnostics After Code Edits

Hermes can run language servers in the background and attach semantic diagnostics to successful write_file and patch operations. This catches problems that a syntax parser cannot see, including undefined symbols, type mismatches, missing imports, and project-aware errors.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/features/lsp

When diagnostics run

LSP is gated on Git workspace detection. Inside a repository, Hermes performs the fast syntax check first and asks the language server for semantic diagnostics when syntax is clean. Outside a Git workspace, it keeps the syntax-only fallback.

Language-server failure does not block a write. Missing, slow, or crashed servers fall back safely, which means a clean edit result is not proof that semantic analysis ran. Check LSP status when the signal matters.

Coding checklist

Work inside the intended Git repository.
Confirm the language server for the file type is available.
Keep project dependencies installed enough for meaningful analysis.
Read both syntax and LSP result fields after an edit.
Fix newly introduced errors before broadening the change.
Run the project's native type checker and tests as the release gate.
Watch backend warnings for required companion tools.
Restart a crashed server before trusting later edits.

Understand the signal

Hermes reports diagnostics introduced by the edit rather than dumping every pre-existing project warning. Some servers need time to index a repository, so the first edit after startup may produce less information than later ones. LSP feedback complements tests; it does not replace runtime verification.

Pitfalls

Assuming syntax-clean means type-correct.
Editing outside a Git repository and expecting LSP output.
Ignoring backend warnings such as a missing shell analyzer.
Treating a silent fallback as a semantic pass.
Fixing unrelated pre-existing warnings during a narrow change.
Shipping after LSP without running the real project test command.

Verification steps

Run hermes lsp status in the target repository.
Confirm the expected language server is detected.
In a disposable branch, introduce one temporary semantic error.
Apply the edit with a file tool and inspect the LSP diagnostics.
Revert the error and confirm the new diagnostic clears.
Run the native type checker, linter, and focused tests.
Check agent logs if a server starts, crashes, or never returns diagnostics.