CodeGraph LSP server

The CodeGraph language server exposes graph-backed code intelligence to an LSP client. It reads an existing GoCPG-managed DuckDB CPG; it does not build or refresh that graph.

Prerequisites

Before starting the server:

1. Install CodeGraph so that the codegraph-lsp console entry point and its LSP dependencies are available.
2. Build or update the target project CPG with the supported project workflow.
3. Confirm that no writer is replacing or migrating the database during the editor session.
4. Keep the database path inside the approved customer workspace.

Verify the entry point

codegraph-lsp --help

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

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

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

OpenCode routes an LSP server by file extensions. Adapt the command and file set to the installed environment:

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

The angle-bracket path is a placeholder, not valid JSON configuration for a real session. Replace it with the exact customer-approved CPG path.

Advertised capabilities

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;
• textDocument/codeAction for supported quick fixes;
• diagnostics published after a document is opened or saved.

Diagnostics can include security findings, dead methods, cyclomatic complexity and non-security pattern findings. Results depend on the tables and columns present in the selected CPG. A query failure can produce an empty feature result, so the editor displays only findings returned by the current CPG query. Confirm the code state with the repository checks used for the change.

Hover, CodeLens and quick fixes

Hover reads method complexity, fan-in, fan-out, callers, LOC, parameter count, flags and security-finding count when the current schema supports them.

CodeLens displays callers and callees for methods and may append a taint path derived from edges_reaching_def.

A quick fix is offered only when a diagnostic’s persisted match_data contains a fix value. Review every edit before saving: the language server returns the stored replacement and does not establish semantic correctness for the whole program.

Freshness and path matching

The LSP server opens read connections to the selected CPG 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.

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

Connection behavior

The server creates a small query pool and releases a connection after each request. An exhausted or locked pool usually indicates a concurrent writer, slow query, unavailable graph or an interrupted client. Restarting the LSP client may clear an interrupted session, but it will not repair a stale or invalid CPG.

Maintained sources

• pyproject.toml registers the codegraph-lsp console entry point.
• integrations/opencode/codegraph_lsp/__main__.py defines CLI options and transport selection.
• integrations/opencode/codegraph_lsp/server.py defines LSP capabilities and request handlers.
• integrations/opencode/codegraph_lsp/diagnostics.py, hover.py, codelens.py and codeaction.py define the current results.

Current source and codegraph-lsp --help are authoritative when this guide differs from the installed revision.