Anchoring notes to code

A note attached to src/auth.ts:82 is worth far more than the same note sitting in a document. This is how the link is made, what it looks like in the editor, and what happens when the code underneath it moves.

Creating a linked note

Any of these will create a note bound to a specific file and line:

Press Ctrl+Alt+Q (Cmd+Alt+Q on macOS) with the cursor on the line.
Right-click in the editor and choose Add DevNote Here.
Run DevNotes: Add DevNote Here from the Command Palette.

The link is captured from wherever the cursor is at that moment. If no editor is focused when you trigger the command, you get an ordinary unlinked note instead — nothing fails, you just do not get the anchor.

The stored link has three parts: the workspace-relative path, the 1-based line number, and a copy of the text of that line as it read when you made the note. That third part is what makes the link survive editing, and it is explained below.

What you see in the editor

The gutter icon

Every line with a note attached gets a sticky-note icon in the gutter, to the left of the line number. The line is also marked in the overview ruler — the narrow strip beside the scrollbar — so you can spot annotated regions in a long file without scrolling through it.

The hover

Hover anywhere over the text of an annotated line and the note's title appears in VS Code's standard hover widget, alongside whatever your language server has to say about that line.

Why not hover the icon?

VS Code has no API for attaching a tooltip to a gutter icon — the gutter is outside the text surface and never fires hover providers. The hover is registered on the line text instead, which is the supported mechanism.

The status bar

When the file you are looking at has notes pointing at it, the status bar shows N notes here. Its tooltip lists the note titles, and clicking it opens the DevNotes+ panel. Archived notes are not counted.

Jumping back to the code

Every linked card in the sidebar can take you to its line — open the file and move the cursor to the exact position. This is the direction most people use it in: you are reading notes, you want the code.

The Command Palette equivalent is DevNotes: Jump to Linked File.

When the code moves

This is the hard part of anchoring notes to line numbers, and DevNotes+ handles it in two ways.

Renamed and moved files

If you rename or move a file inside VS Code, every note pointing at it is updated to the new path automatically.

Limitation

This relies on VS Code's rename event. A file renamed outside the editor — with git mv, your shell, or another program — will not be picked up, and notes pointing at the old path will not resolve until you re-link them.

Lines that drift

Adding twenty lines to the top of a file would ordinarily leave every note in it pointing twenty lines too high. DevNotes+ corrects for that by remembering the content of the anchored line, not just its number.

When a file is opened or saved, DevNotes+ searches within 100 lines either side of each note's stored position for a line matching the remembered text. If it finds one somewhere else, the note's line number is quietly updated and the gutter icon moves with it.

Two details worth knowing:

Short lines are skipped. A stored line has to be at least 10 characters after trimming to be used as an anchor. A lone } matches everywhere and would be worse than useless.
Duplicate lines are disambiguated. When several notes are anchored to identical text, each one is assigned to a distinct occurrence — nearest first — so they do not all collapse onto the same line when a block of code is inserted above them.

If the anchored line is deleted outright, or edited past recognition, the note keeps its last known position. It does not disappear, and it does not jump somewhere arbitrary.

Tip

Anchor notes to something distinctive — a function signature, a named constant, a specific condition — rather than to a blank line or a closing brace. The more particular the line, the better drift recovery works.

Several notes, one line

Nothing stops you attaching more than one note to the same line. The gutter shows a single icon, and the hover lists every note title bound to that position.

Notes without a link

Plenty of notes are about the project rather than a line of it — a decision record, a meeting summary, a release checklist. Create those with + New in the sidebar and leave them unlinked. They behave exactly like linked notes everywhere else: tags, branch scoping, reminders, sharing and Claude Code access all work the same way.