Annotate & share notes without touching source

Annotations let you attach notes — comments, to-dos, task assignments, whiteboard images, linked documents — to a specific entity, file, or line, without editing the source code. The notes live with the project and show up right next to the code they describe.

Add an annotation

Any of these work:

• Right-click an entity, file, or selection → Annotate.
• Hover the editor's right gutter on a line and click the annotation indicator to annotate that line.
• Use the top-level Annotations menu → Annotate (with Annotate Selection and Annotate Current Line entries).

An annotation card opens where you type the note. There are no factory-default keyboard shortcuts for annotating, but the annotate actions are bindable, so you can assign your own keys.

An annotation on main: the marker in the editor, and the card with author, timestamp, and the note — none of it touches the source file.

Organize with #tags

Type #tag in the note body to tag it — great for to-do lists, prioritizing work, or flagging areas to refactor. To write a literal #, type ##.

For a lighter, private per-line marker (no note, not shared), use a bookmark instead.

Where annotations appear

• In the editor — inline in the source, or as margin indicators on annotated lines (choose inline, indicators, or none in settings).
• Annotation Viewer — a dock showing the annotations for the file in the active editor.
• Annotations Browser — a dock (Annotations → Browse All Annotations) listing every annotation in the project, so you can search across all of them.
• Information Browser — an annotation section on each entity.

Notes survive re-parses

If the entity an annotation was attached to is deleted or moved, the note isn't lost — it becomes an orphan you can review and re-attach to another entity, rather than disappearing.

How annotations are stored — and shared

Annotations are saved as JSON inside your .und project directory, one file per author, named ann_<author>.json (for example ann_natasha.json). The author defaults to your OS login name and is overridable in settings. Each file records, per note, the entity (by unique name), file/line anchor, body text, author, and timestamps.

Because every author writes a separate file and Understand loads them all together, several people's notes coexist without overwriting each other. To share annotations with your team, put those files (or the project directory) under version control — everyone who opens the project sees the combined set.

The AI Overview is an annotation too

Understand's AI-generated descriptions use the exact same annotation system, written under a virtual author (e.g. ann_AI Overview.json). That's why AI descriptions are shareable the same way — and why they never modify your source. See What can the AI access? and Understand AI: overview & setup.