Markdown Markup 
Leave threaded comments on Markdown through VS Code's native Comments UI — the
same gutter threads and Comments panel used by PR-review extensions — while the
comments live inline in the .md file as CriticMarkup.
No sidecar, no database, no server: the file stays plain text and agent-native,
so a coding agent like Claude Code can read, reply to, and resolve your notes by
editing the raw text.
{==anchored span==}{>>#a1b2 @till: is this cap right? | @agent: capped at 3<<}
{==…==} — the highlighted anchor span.{>>…<<} — the comment, immediately after the anchor (no space between).#a1b2 — a 4-char stable id that keeps the live thread mapped to the text as it shifts.@author: — author prefix. Replies follow after |, each with its own @author:.- Point comment (no anchor): a bare
{>>#id @author: text<<}.
- Resolve = remove the marks. Open comments == the count of
{>> (grep -c '{>>' file.md).
Resolving an anchored note keeps the prose and just unwraps {==…==}.
Usage
- Comment: select a phrase →
Cmd/Ctrl+Alt+M (or right-click → Comment on Selection)
and type your note. With no selection you get a point comment at the end of the word
under the cursor. For a multi-line, wrapping editor, use the gutter + to open
VS Code's native comment widget.
- Reply / Edit / Delete: the buttons on a thread and its comments, or the editor
hover actions.
- Resolve: the ✓ button in a thread's header removes its marks (keeping anchored prose).
- Hover a mark in the editor for Reply · Edit · Resolve links without opening the widget.
- Navigate:
Cmd/Ctrl+Alt+] / Cmd/Ctrl+Alt+[ jump between marks.
The author label comes from markdown-markup.author; if unset it falls back to
git config user.name, then "me".
Marks can't be nested, and notes containing the grammar's delimiters ({== ==},
{>> <<}, or the | @name: reply separator) are refused with a toast rather than
silently corrupting the file.
Highlighting
In the editor the anchored span gets a highlighter-yellow background (like ==mark==)
and the rest of the mark is muted like a <!-- --> comment. The colors are
theme-contributed and overridable:
"workbench.colorCustomizations": {
"markdownMarkup.anchorBackground": "#ffe44040",
"markdownMarkup.commentForeground": "#7aa96b"
}
The threaded Comments list lives in the bottom panel by default (it's a core VS Code
view, so an extension can't relocate it). To move it to the secondary sidebar,
show it (View → Appearance → Secondary Side Bar, Cmd/Ctrl+Alt+B) and drag the
Comments view tab into it — VS Code remembers the placement.
The extension defaults comments.openView to "never" so the Comments view stays
closed until you open it. Set it to "file" if you'd prefer it to reveal itself
whenever the open file has comments.
Markdown preview
Marks render in VS Code's built-in preview (read-only): anchored spans are highlighted,
the raw syntax is hidden, and hovering a mark shows the thread with markdown-processed
text. Authoring and resolving happen in the editor.
Development
npm install
npm run compile # bundle with esbuild -> dist/extension.js
npm run check-types # tsc --noEmit
npm run lint # eslint
npm test # node:test unit tests for the grammar
Press F5 to launch an Extension Development Host, then open sample.md.
Scope
MVP: anchored + point comments, threaded replies, resolve, next/prev, editor
highlights, and preview rendering. Not yet: suggested edits ({++…++} / {--…--})
or a Marketplace release.
