LSP Navigation and Diagnostics

Use lsp_navigation as PRIMARY for code intelligence. Use lens_diagnostics with source=lsp as PRIMARY for proactive type/error checks. Do NOT use grep/glob/ast-grep first for code intelligence.

Aggregate-tool hosts

Some hosts expose pi-lens through a single aggregate tool — lens(action=...) — instead of registering the standalone names below. On those hosts:

• Proactive checks: lens({ action: "lsp_diagnostics", ... }) — same parameters as the table below; the cached-report entry point maps to lens({ action: "diagnostics", ... }).
• If lsp_navigation is not among the aggregate's actions, do not call the standalone name: use the host's structural search funnel (symbol_search → module_report → read_symbol) or the ast-grep CLI for navigation instead.

Diagnostics

Use lens_diagnostics with source=lsp before builds/tests or after touching several files:

Prefer explicit paths batches after multi-file edits — bounded concurrency, no unrelated directory noise.

Parameter reference

lens_diagnostics accepts source: "session" | "lsp" and scope: "paths" | "workspace". Use mode: "delta" for the current turn, "all" for the cache-only session view, or "full" for an active scan. path selects one file or directory; paths filters a batch. severity is "error", "warning", or "all"; serverScope is "primary" or "all".

For mode: "full", refreshRunners: "cached" | "cheap" | "all" | "none" (or false/true) controls project analyzers. The first three string modes can launch a fresh heavyweight analyzer pass, bounded by the slowest runner's roughly 180-second ceiling; none disables it. maxProjectFiles limits cheap project runners, maxLspFiles limits the LSP sweep, and includeGenerated: true includes generated-name paths. These three limits apply to full scans. concurrency and waitMs tune LSP batches.

Navigation (Code Intelligence)

The operation values are definition, typeDefinition, declaration, references, hover, signatureHelp, documentSymbol, findSymbol, workspaceSymbol, codeAction, rename, rename_file, implementation, prepareCallHierarchy, incomingCalls, outgoingCalls, executeCommand, workspaceDiagnostics, and capabilities.

For findSymbol, pass query; optionally narrow with kinds, exactMatch, topLevelOnly, and maxResults. rename_file uses newFilePath. symbol resolves a character automatically; character: -1 requests automatic resolution, and symbol#N selects a numbered symbol when the result lists one. callHierarchyItem is the object returned by prepareCallHierarchy and is required by the incoming/outgoing follow-up calls.

Output is text by default, the shape a Neovim LSP user sees: a path:line:col location list for definition, references, implementation and call hierarchy; hover's markdown (a language-bearing snippet as a fenced code block); an indented start-end kind name symbol tree for documentSymbol and findSymbol; path:line:col: severity: message rows for workspaceDiagnostics, under a path (scanned 5m ago) header per file when the snapshot stamped its age; and the rename summary, or the completed edit list after applying (with a warning when the server dropped a conflicting edit). A call-hierarchy entry prints its call sites on indented path:line:col lines under the symbol, and prepareCallHierarchy adds a callHierarchyItem: <json> line carrying the item verbatim. Pass view: "json" only when you need the structured envelope (the pre-text default, byte-identical), for example to parse locations or metadata.searchReads.

An executed executeCommand value is the one exception: its payload is the server's arbitrary JSON, so it prints as compact single-line JSON with no line shape of its own. A command the client refused or timed out prints Not executed: <reason>, plus a warning that a timed-out command may still be changing files.

Call Hierarchy Pattern

// Step 1
lsp_navigation(operation="prepareCallHierarchy", path="src/api.ts", line=42, character=10)
// → symbol line, then `callHierarchyItem: <json>`: pass that JSON back verbatim

// Step 2
lsp_navigation(operation="incomingCalls", callHierarchyItem=<item from step 1>)
lsp_navigation(operation="outgoingCalls", callHierarchyItem=<item from step 1>)

Operational Notes

• definition returns nothing? The file may not be open/indexed yet. Read it first, then retry.
• workspaceSymbol empty? Always pass path. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
• references — query from the definition site for full cross-file coverage; usage-site queries can be partial.
• signatureHelp — only valid at call-site argument positions; declaration positions return empty.
• workspaceDiagnostics — tracked push snapshot only, not an active check. Use lens_diagnostics with source=lsp when you need fresh results.
• codeAction — distinguish quickfix from generic refactors ("Move to new file"). Generic refactors are not error fixes.
• prepareCallHierarchy — server-capability dependent; if unsupported, skip incoming/outgoing calls.

When NOT to Use LSP Navigation

Golden Rule

Code intelligence → lsp_navigation first. Type/error validation → lens_diagnostics source=lsp first. Text/pattern search → grep/ast-grep.