pyrefly-lsp

name	pyrefly-lsp
description	Do not invoke. Infrastructure-only — the sibling `.lsp.json` registers the pyrefly Python language server (`pyrefly lsp`) with Claude Code's built-in LSP tool, giving go-to-definition, find-references, call hierarchy, and document symbols for .py/.pyi files. There is nothing to run here.
metadata	{"project":"saitenka"}

pyrefly-lsp

Infrastructure-only plugin. Its purpose is the sibling .lsp.json, which registers pyrefly lsp as the Python LSP server for Claude Code's LSP tool. Portable command (pyrefly on PATH) so a contributor who runs uv tool install pyrefly gets symbol navigation on clone.

• Server binary: pyrefly on PATH (uv tool install pyrefly; upgrade with uv tool upgrade pyrefly).
• Nothing to invoke. Claude should never trigger this as a skill.
• Nav backend only. pyrefly here backs the interactive LSP tool; basedpyright remains a blocking checker in the poe types gate (see the dev-gate skill). Different jobs.
• The LSP tool binds its server at session start, so a Claude restart is required after enabling.

Trusting the answers

The reference index is built once per server and only ever catches up through file watchers that Claude Code does not enable — so it silently drifts from disk as a session runs. Verified in pyrefly/lib/lsp/non_wasm/server.rs (v1.2.0): indexed_configs / indexed_workspaces are insert-only sets, and setup_file_watcher_if_necessary registers nothing unless the client advertises didChangeWatchedFiles.dynamicRegistration (silent _ => () otherwise).

It answers a stale query with a plausible wrong result, never an error — most often just the definition itself. That reads exactly like "this symbol has no callers", which is how it produces a confidently wrong refactor.

• hover / documentSymbol are always trustworthy — they read the open document, not the index.
• findReferences / incomingCalls / rename need the index. A lonely result is a failure signal, not a finding: re-query, then corroborate with git grep before acting on it.
• The first query of a session can outrun the background index. One measured session returned 1 reference, then 34 for the same symbol moments later. Never conclude from the first call.
• Restart the session after disk moves under the server — branch switch, rebase, merge, a codemod writing new modules. Not after a commit: committing changes nothing on disk, so it cannot stale the index.
• Do not set disable-project-excludes-heuristics. It addresses the editable-install defect of facebook/pyrefly#2667 / #3553 / #3704, which this repo does not have — a fresh server indexes this tree completely with the heuristics active — and it would pull .venv into the indexed set.