the moment
A 400-line plan just landed. Now what?
You know the drill: the agent finishes a plan, and the next move is yours. Reading raw Markdown in an editor hides what a reader would see — tables, structure, the shape of the argument. Pasting chunks back into the chat divorces every comment from the place it's about, and the agent has to guess where your "this part is wrong" points. And the one tool built for commenting on documents — a pull request — wants the draft committed, pushed, and reviewed in a browser first.
Not every document belongs committed, and not every working version of a doc should be pushed up.
A working draft needs the feedback loop you'd give a coworker at a whiteboard: point at the paragraph, say what's wrong, hand it back. That's what margin notes are.
the loop
Read rendered. Note in place. Hand it back.
Open the draft in PullMark — or just pullmark plan.md from
the terminal your agent runs in. Tables are tables, diagrams are
diagrams, and the page re-renders every time the file changes.
Hover the block that's wrong, click the note bubble, write what you'd tell a coworker. Notes are signed with your @name and anchored to the exact passage — a note above the title covers the whole document.
Tell your agent: "address my notes in plan.md." The notes live in the file as ordinary HTML comments, so the agent reads each one exactly where you left it — applies it, answers it, deletes it.
No lock-in, by construction. A margin note is
<!-- note @you: … --> in the Markdown — a comment that
stays out of the rendered page. Your files stay plain text, your notes
travel with the document, and anything that can read the file can read
the feedback. The margin
notes docs cover the mechanics; the feature is in beta and on by
default.
Agents follow the convention better with one paragraph of context.
This is the same text behind the Copy button in
Settings → Experimental — paste it into your agent's
instructions file (CLAUDE.md, AGENTS.md) or the
conversation:
## Margin notes Markdown files may contain review notes as HTML comments: `<!-- note @name: comment -->` (possibly multi-line, closing with `-->` on its own line). Each note sits directly after the passage it's about; a note above the first heading is about the whole document. `--\>` inside a note means a literal `-->`. When asked to address notes: work through each one, apply or answer it, and DELETE the note (with its surrounding blank line) once addressed. To reply or ask instead, leave your own note in the same format below the original, signed with your own @name. Don't add notes to code examples inside fenced blocks. A note about one list item sits inside that item — directly after the item's last line, indented to the item's content, with no blank lines around it. Keep (or delete) the whole indented comment; its indentation is what ties it to the item.
long documents
Notes that wait for you.
A thorough review of a long document — a research write-up, a complex design doc — can take an hour. Margin notes are built for that hour. The document holds still while you work: write the thought where it strikes and keep reading. When page thirty changes your mind about the note you left on page three, go back and sharpen it — or delete it. Nothing reaches your agent until the pass is done and your notes agree with each other, so the feedback lands as one coherent set instead of a running stream of corrections.
It earns its keep even for documents that will end up committed. Do the rough first pass in margin notes before the first commit, and the pull request opens clean — reviewers see the conversation that matters, not the scaffolding it took to get there.
the revision
Watch the edits land.
While the agent works through your notes, PullMark keeps up. The page
re-renders on every save, and Compare shows the revision
as a rendered diff — the agent's edits highlighted word by word, live as
they land. One click compares the working file against any recent commit
or branch; pullmark --diff plan.md does it from the
terminal. It's the fastest answer to "what did the agent just change
in my doc?" — and when the notes are addressed, they're simply gone
from the file.
when it is a PR
And when the doc does go up for review…
Some documents do belong committed — and agent-heavy repos fill pull requests with Markdown: plans, ADRs, agent definitions, runbooks. PullMark shows those PRs as rendered diffs with just the changed words highlighted, lets you comment and suggest on the exact blocks, and submits your review to GitHub. The overview knows where the PR stands: decision, reviewer verdicts, checks, and the conversation as a readable timeline.
Close the loop with your agent.
Free, open source, signed and notarized. macOS 13+.
$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmarkThe latest DMG — open it, drag to Applications (PullMark handles the cleanup). All releases →
Either way, PullMark checks for updates and installs them with one click.