Lsp Dead Code

Requires the agent-lsp MCP server.

lsp-dead-code

Audit an exported symbol list for zero-reference candidates. Calls list_symbols to enumerate symbols, then checks each exported symbol with find_references to find callers. Produces a classified report.

When to Use

Use this skill when you want to identify dead code in a file — exported symbols that are defined but never called anywhere in the workspace. Common use cases:

• Cleaning up APIs before a release
• Identifying legacy exports that can be safely removed
• Auditing a package for unused public surface area

Important: This skill surfaces candidates. Always review results manually before deleting anything. See the Caveats section below.

What counts as "exported"

Prerequisites

If LSP is not yet initialized, call mcp__lsp__start_lsp with the workspace root first:

mcp__lsp__start_lsp({ "root_dir": "/your/workspace" })

agent-lsp supports auto-inference from file paths, so explicit start is only required when switching workspaces or on a cold session.

Step 0 — Verify indexing is complete (mandatory)

Do not skip this step. An under-indexed workspace returns [] for symbols that ARE referenced, producing false dead-code candidates.

Pick one symbol you know is actively used (e.g. the primary constructor, a widely-called utility function). Call find_references on it:

mcp__lsp__find_references({
  "file_path": "/abs/path/to/file.go",
  "line": <known-active symbol line>,
  "column": <known-active symbol column>,
  "include_declaration": false
})

If this returns []: the workspace is not indexed. Wait 3–5 seconds and retry. Do not proceed until a known-active symbol returns ≥1 reference. If it never returns results after 15 seconds, restart the LSP server with mcp__lsp__restart_lsp_server and re-open the target file.

Step 1 — Open the file and enumerate symbols

Open the file so the language server tracks it, then fetch all symbols:

mcp__lsp__open_document({ "file_path": "/abs/path/to/file.go" })

mcp__lsp__list_symbols({ "file_path": "/abs/path/to/file.go" })

Collect the full symbol list. Filter to exported symbols only using the language-appropriate rule from the table above.

Coordinate note: list_symbols returns 1-based coordinates. Pass selectionRange.start.line and selectionRange.start.character directly to find_references — no conversion needed.

"no identifier found" error: This means the column points to whitespace or a keyword rather than the identifier name. This happens with methods whose receiver prefix shifts the name rightward (e.g. func (c *Client) MethodName — the name starts at column 21, not column 1). Fix: grep the declaration line for the symbol name to find its exact column:

grep -n "MethodName" file.go
# count characters to find the 1-based column of the name

Then retry find_references with the corrected column.

Step 2 — Check references for each exported symbol

For each exported symbol, call find_references with include_declaration: false so the definition site itself is excluded from the count. A count of 0 means no callers, not no occurrences.

mcp__lsp__find_references({
  "file_path": "/abs/path/to/file.go",
  "line": <selectionRange.start.line>,
  "column": <selectionRange.start.character>,
  "include_declaration": false
})

Record the result for each symbol:

{ symbol_name, kind, line, reference_count, locations[] }

Batching note: For files with many exported symbols (>20), process in batches of 5–10 to avoid overwhelming the LSP server.

Zero-reference cross-check (required before classifying as dead): When find_references returns [] for a symbol that looks foundational (a handler, a constructor, a type used as a field), do not trust LSP alone. LSP can miss references made through value-passing, interface satisfaction, or function registration patterns (e.g. server.AddResource(HandleFoo)). Before classifying as dead, run a text search in the primary wiring files:

grep -r "SymbolName" main.go server.go cmd/ internal/

If grep finds the name in a registration or assignment context, the symbol is active — LSP just couldn't resolve the indirect reference. Update your classification accordingly.

Step 3 — Classify and report

Classify each exported symbol by reference count:

• Zero references (LSP + grep) — confirmed dead candidate. Flag with WARNING.
• Zero LSP, found by grep — active via registration/value pattern. Mark as ACTIVE.
• 1–2 references — review manually. May be test-only usage.
• 3+ references — active symbol. Not dead code.

For test-only references: if all locations are in _test.go files (Go) or files named *.test.* / *.spec.*, mark the symbol as "test-only" in the report rather than "zero-reference".

Produce the Dead Code Report using the format in references/patterns.md.