Skip to content

Understand for VS Code (extension)

This page describes a separately distributed product

The Understand for VS Code extension is maintained and distributed separately from the desktop application (it's installed from the VS Code Marketplace), so it isn't built from this documentation set's source. Treat the steps below as a getting-started orientation and confirm current details — supported languages, commands, and settings — in the extension's own listing and documentation.

The Understand for VS Code extension brings Understand's analysis into Visual Studio Code. It talks to userver, the Understand language server that ships with the desktop install, and surfaces Understand's code navigation and CodeCheck violations inside the editor you already work in.

Not the same as pointing Understand at VS Code

This is the reverse direction of using VS Code as an external editor. There, Understand launches VS Code to open files. Here, the extension runs inside VS Code and pulls analysis from Understand. If you only want files to open in VS Code from the Understand GUI, you don't need this extension.

1. Install Understand (you get userver with it)

Install the desktop application. It includes userver, the language server the extension connects to.

2. Make userver reachable from VS Code

VS Code (Node.js) needs userver on the system PATH:

  • Windows: the installer adds the Understand bin directory to your PATH by default (an option under Advanced Install); add it yourself if that option was turned off.
  • macOS / Linux: create a symlink to the userver executable in a directory on your PATH (Node.js ignores the shell PATH the installer sets, so a symlink into a standard location such as /usr/local/bin is the reliable approach).

3. Install the extension

Install Understand for Visual Studio Code from the VS Code Marketplace.

4. Create a project

The extension reads an Understand project, so create one first:

  1. In Understand, create a project from your source (this produces a .und folder).
  2. If you want CodeCheck violations to appear in VS Code, configure a CodeCheck run to execute in the background so results are available to the extension.

5. Open your code in VS Code

Open the folder/workspace that contains those source files. If a .und folder is visible in the file explorer, the extension starts automatically; otherwise, open a source file in a supported language to start it. Once running:

  • The language server starts for supported languages — the status bar at the bottom-left shows its connection state (hover to confirm it's connected).
  • A .und folder found in the workspace is selected automatically by the language server.

If something doesn't connect, re-check that userver is on the PATH (step 2) and that a .und project exists, then consult the extension's own FAQ.

CodeCheck violations in VS Code

The Problems panel and the extension's Violations view show the same violations as Understand's Violation Browser: your background configurations' results plus any SARIF imports you've synced.

Changes you make in Understand while VS Code has the project open — turning Run in Background on or off, syncing an import, setting a baseline, adding a configuration or a check — are picked up without reopening the project. New checks and configurations count from the next analysis.

Each violation appears at the severity its configuration sets for the check:

Configured severity Problems panel
High and above Error
Medium Warning
Low, Informational Information

Analysis errors are always errors. To keep checks out of code you don't own, see exclude third-party paths.

Customize the hover

The understand.hover setting replaces the hover's built-in declaration for the entity kinds you choose. Each key is a kind filter (a comma separates alternatives, ~ excludes); each value is the text to show:

"understand.hover": {
  "Function": "{kind} {longname}({parameters})",
  "Python Function": "def {name}({parameters})"
}

Placeholders: {name}, {longname}, {kind}, {type}, {parameters}, {value}. One the entity has no value for is left empty; an unknown one is left as written. When several keys match, the narrowest wins, so Python Function beats Function for a Python function. Kinds with no matching key keep the built-in declaration.