Skip to content

Build an Understand plugin with AI

An AI coding assistant can write a working Understand plugin for you — a custom graph, metric, report, or check — far faster than starting from scratch. The catch is that a general model doesn't know Understand's Python API and will invent plausible-looking calls. This guide is about closing that gap: grounding the AI in the real API so what it writes actually runs.

A plugin might not be what you need

Understand's MCP server is a different beast: it doesn't help an AI write plugins — it's an alternative to writing them. If what you really want is information out of Understand — who calls this, what depends on that — connect your AI agent via MCP and let it query the project directly, no code required. Write a plugin when you want something that runs inside Understand — a graph, metric, report, or check your team can rerun from the menus.

Why grounding matters

Understand plugins are Python scripts that define one entry-point function (draw, value, check, generate, or build) — see Write a plugin. The API is specific (understand.Ent, understand.Ref, kinds, filters), and an ungrounded model tends to hallucinate method names. Give the AI the facts and most of that disappears.

1. Give the AI access to the real API

Point the AI at the generated Python API reference, the API guide for the plugin type you're building (Graphs, Metrics, CodeCheck, Interactive Reports, Architectures), and the working plugins in the script cookbook / the shipped plugins/ tree. Concrete examples of the entry-point function you want are the single biggest accuracy boost.

2. Iterate in a tight loop

  1. Describe the plugin and its type (graph/metric/report/check/architecture). Tell the AI the entry-point function it must define.
  2. Prototype as a standalone script first, run it with upython (Python API: getting started), and feed errors back to the AI.
  3. Wrap it as a .upy with the entry point plus name(), install it (drag-and-drop), and run it from the matching menu. Use Rescan Plugins in the Plugin Manager after each edit — or Tools → Reload All Plugins, which is the same action without the dialog.

3. Watch for the common failure modes

Review AI-written plugins before trusting the output

  • Hallucinated API — verify every unfamiliar call against the reference; if it isn't in the API, it's invented.
  • Scope creep — plugins can grow large fast. Keep the first version small and working, then extend.
  • Correctness — a plugin that runs isn't necessarily right. Check its output against a case you can verify by hand before relying on it.

4. Package and share

Once it works, share it like any plugin — install via the Plugin Manager, or drop the .upy into a project's plugin/ folder so teammates get it automatically.

Where to next