imark-comments

Imark comments

Imark is a macOS markdown reader that stores a reader's comments inside the document, as HTML comments. Every renderer ignores them, grep finds them, and they travel with the file. If you are looking at a markdown file with blocks like this, that is what they are:

Rows move in batches of 500, and the deadline is generous but workable.

<!-- imark quote="generous but workable" by="alex" at="2026-08-02T14:31Z"
Workable with which team? This needs a number, not an adjective.
-->

Reading them

Do not hand-roll a parser:

node "${CLAUDE_PLUGIN_ROOT}/scripts/imark.mjs" notes <file.md>

By default this shows only the notes still asking for something. A note carrying resolved= has been dealt with — it stays in the file as the record of what was asked, but it is history, not work. The header says how many were left out. Add --all when the history is what you want.

Add --json for structured output; it obeys the same rule. Each note comes back with what it says, the quote it is attached to, who wrote it and when, the heading it falls under, and the block above it.

The format

Attribute	Meaning
quote=	the exact words the note is attached to. Required
by=	who wrote it. Omitted when there is no name
at=	ISO 8601 timestamp
nth=	which occurrence of the quote, when the same words appear twice. Only written when it is above 1
color=	one of five names. Omitted for the default
resolved=	ISO date stamped by whoever acted on the note. The app fades it; review rounds stop repeating it

The body is every line between the opening line and a line containing only -->. Inside it, & is a literal & and --> is a literal --> — escaped so the note cannot close its own comment early. In attributes, " is a quote character.

Acting on them

A note is a request, not a remark. Answer every one, say what you changed for each, and refer to them by their quote — “on ‘generoso mas exequível’” — which is how the user sees them in the app.