Skip to main content

CodeGraph LSP server

Connect an LSP client to CodeGraph through GoCPG gRPC, verify diagnostics and method information, and diagnose missing results.

User Guides

The CodeGraph LSP server helps you inspect methods in your editor: view complexity, call relationships, and analysis findings alongside the source. Use it when learning a repository or reviewing a change. Open a method, inspect its metrics, and follow its relationships to understand the surrounding code.

The editor sends requests through the Language Server Protocol (LSP). CodeGraph matches the open file URI to a path in the existing CPG and queries that graph through GoCPG gRPC. Refresh the CPG through the project workflow before reviewing a new revision.

What the editor shows

What the editor shows
Task LSP feature Result
Assess a method before changing it Hover Complexity, size, parameter count, and call relationships in a tooltip.
Inspect a method’s context CodeLens Caller and callee counts above the declaration, plus an available taint-flow hint.
Review analysis findings Diagnostics on open and save Findings attached to lines in the file.

Prerequisites

Before starting the server:

  1. Install CodeGraph and its dependencies using the local source setup in the CLI guide. Activate that Python environment so that codegraph-lsp is available to the editor process.
  2. Build or update the target project CPG using the project import guide.
  3. Confirm that no writer is replacing or migrating the database during the editor session.
  4. Select the database for the project opened in the editor and confirm that the GoCPG service can read it.
  5. Make GoCPG gRPC available to the LSP process at localhost:50051. LSP uses this default address for CPG queries.

Verify the entry point

codegraph-lsp --help

Start the standard input/output transport with an existing graph:

The examples use PowerShell. The working directory is not significant when the console command is installed. Replace the quoted placeholder below with the approved database path, as seen by the GoCPG service. Keep the quotes when the path contains spaces. Use the same graph as the repository opened in the editor.

codegraph-lsp --db "<cpg.duckdb>"

The source checkout also supports python -m codegraph_lsp as a compatibility entry point, but installed client configuration should prefer the console command.

Supported options

Supported options
Option Meaning
--db <cpg.duckdb> Required path to the GoCPG-managed CPG.
--complexity-threshold <integer> Complexity diagnostic threshold; default is 10.
--transport stdio|tcp LSP transport; default is stdio.
--host <address> TCP bind address; default is 127.0.0.1.
--port <integer> TCP port; default is 2087.
--log-level debug|info|warning|error Server logging level; default is info.

TCP mode is intended for a controlled local or protected network boundary:

codegraph-lsp --db "<cpg.duckdb>" --transport tcp --host 127.0.0.1 --port 2087 --log-level info

The server does not add authentication or TLS to TCP transport. Do not bind it to an untrusted interface without an approved protective layer.

OpenCode example

Create opencode.json in the root of the project you open in OpenCode and save the configuration below. If the file already exists, add the codegraph object to its lsp section and keep the other settings.

OpenCode routes files to an LSP server by their extensions. Set the command from your installed Python environment and the extensions used by your project:

{
  "lsp": {
    "codegraph": {
      "command": ["codegraph-lsp", "--db", "<cpg.duckdb>"],
      "extensions": [".py", ".go", ".js", ".ts", ".java", ".c", ".cpp"]
    }
  }
}

Replace <cpg.duckdb> with the exact path to your project CPG before starting the client. The remaining JSON structure is ready for the lsp section. Escape Windows backslashes in JSON, for example C:\\workspace\\project.duckdb.

Restart the client’s LSP connection after changing this configuration. Open a file present in the selected graph and save it. Verify the client’s initialize response, server logs, published diagnostics, hover on a known method, and CodeLens results. Compare returned filenames and method information with the current source. To verify a graph query, choose a known method: hover should show its name and metrics, and CodeLens should show its call relationships.

Events and analysis results

The server handles document open, save and close events. It currently advertises:

  • textDocument/hover for method metrics;
  • textDocument/codeLens for caller/callee counts and an available taint-flow hint;
  • diagnostics published after a document is opened or saved.

Diagnostics show dead-method and complexity findings from the selected CPG. For a method whose complexity exceeds --complexity-threshold, the server publishes a high-complexity finding. Closing a file clears its diagnostics.

For example, a method with complexity 11 and threshold 10 receives a high-complexity finding at its declaration. Open the method tooltip and check its complexity. After changing the code, close the LSP connection and refresh the graph through the project workflow. Reconnect, save the file, and check the new value. If it is now 10 or lower, the finding for exceeding that threshold disappears.

If an expected finding is missing, check the query log and the selected CPG tables and columns using the “Freshness and path matching” section.

Hover and CodeLens

Hover shows method complexity, incoming and outgoing relationships (fan-in and fan-out), calling methods (callers), size in lines (LOC), parameter count, and method flags.

Use fan-in to see how many methods depend on the selected method and fan-out to see how many methods it calls. LOC shows its size in lines. Together with complexity, these metrics help you choose a section for detailed review and assess the size of a change.

CodeLens shows caller and callee counts. When dataflow analysis results are available, it also shows a data propagation (taint) path. The taint: source→sink hint names the methods at either end of the detected relationship.

Rule-based changes

Use the pattern search guide to find and fix pattern matches. Generate and review the diff first, then apply the selected changes and run the project checks. Refresh the CPG and save the file in your editor to see the updated metrics and diagnostics.

Freshness and path matching

The LSP server uses read-only GoCPG query adapters and normalizes file URIs to workspace-relative forward-slash paths. If an editor shows no result:

  1. Check the server log for a startup or query error.
  2. Verify that the selected graph belongs to the opened repository.
  3. Refresh the CPG through the supported project workflow.
  4. Save or reopen the file to request diagnostics again.
  5. Check that stored filenames can match the editor’s workspace-relative path.
  6. Check that GoCPG gRPC is reachable and can query the selected database.

Do not solve a stale graph by editing the DuckDB file directly. Stop or coordinate writers before database maintenance.

Connection behavior

Connection pool exhausted means the server is processing other queries. Wait for them to finish, then repeat the editor action. GoCPG gRPC transport unavailable for LSP means the transport could not be acquired. Inspect the actual error before choosing a recovery action. Restarting the LSP client can clear an interrupted session, but does not repair a stale or invalid CPG or make an unavailable GoCPG service reachable.

Report a documentation issue