Skip to content

Understand AI — overview & setup

Understand AI adds LLM-generated explanations and chat on top of Understand's exact, parsed model of your code. By default it runs a local model entirely on your machine — no source code, prompts, or descriptions leave your computer, and results are saved inside your project so a whole team can share one machine's work. (You can optionally point it at a cloud provider instead — see Choose a model.)

AI complements Understand — it doesn't replace it

Understand's call graphs, dependencies, and metrics are deterministic and exact; the AI layer is probabilistic and best for explaining, summarizing, and onboarding. See Why use Understand when AI does the same thing?.

Turn it on

  1. Open preferences: Tools → Options (Windows/Linux) or Understand → Preferences (macOS).
  2. Go to the Data page.
  3. Turn on Enable AI.

The first time AI runs, Understand performs a short speed test and picks a sensible default for background generation based on your hardware.

The AI Overview

The AI Overview shows a plain-language description of whatever entity (function, class, file…) you're looking at.

  • Right-click an entity → AI Overview, or open the panel and sync to an entity (e.g. Ctrl+Click).
  • Descriptions are generated on demand, and optionally pre-generated in the background (see below).

Background pre-generation

On the Data page, the Automatically Create Overviews setting controls how eagerly descriptions are built:

Setting Behavior
Off Generate only on demand when you view an entity.
For currently opened files Pre-generate for files you currently have open; new files are queued as you open them.
For the entire project Pre-generate for the entire project. This can take hours on a large codebase, but it resumes where it left off if you close and reopen the project.

Overviews can also be generated in batch from the command line with und ai.

Descriptions are stored with the project — and shareable

Generated descriptions are written to ann_AI Overview.json inside your .und project directory. Because it lives in the project, it can be committed to version control: one capable machine can generate descriptions and share them with everyone else on the team — useful when some machines can't run the model themselves (see below).

Hardware & platform requirements

Understand AI is designed to run the model on a GPU. If no suitable GPU is available it falls back to the CPU, which is considerably slower.

Hardware and model size both drive speed and quality

The same question answered by a small model on a laptop and a large model on a well-equipped workstation or server can come back at very different speeds — and with noticeably different answer quality. Which model you're running matters as much as the hardware it's running on. See Choose a model for the size/quality/speed tradeoffs of the bundled options.

  • Recommended: a dedicated GPU with ≥ 6 GiB free VRAM (8 GiB recommended).
  • GPU backend is selected automatically for your platform: Metal on Apple Silicon, Vulkan on Windows/Linux.

Not supported:

  • Intel (x86_64) Macs — AI is disabled on these machines.
  • Virtual machines — typically can't reach GPU hardware.
  • Machines that fail the startup speed test default to AI off (you can still share descriptions generated elsewhere).

Re-run the hardware benchmark

If your GPU has enough VRAM but Understand still chose the CPU (for example VRAM was busy at first launch), free VRAM (a reboot helps), delete the AI server's config file, then relaunch:

  • Windows — %APPDATA%\SciTools\undaiserver.ini
  • Linux — ~/.config/SciTools/undaiserver.conf
  • macOS — ~/Library/Preferences/com.scitools.undaiserver.plist (then run killall cfprefsd)

Where to next