Markdown Collab

Review Markdown with your AI agent — Claude Code, Cursor, Windsurf, Codex or Copilot — in VS Code, Cursor or Windsurf. Comments live inside the .md file, anchored to the text they're about. The agent reads them, replies, and proposes edits you accept or reject. Or it reviews the document and leaves comments for you.

Click Ask agent to review. The agent reads your doc and leaves a comment per concern, and you triage them. The first send asks how to reach your agent and remembers your answer — typing into a running terminal session is the normal path.

What you get

• Comments stored in the file. Each thread is an HTML comment wrapped around the exact passage it points at, so it's invisible on GitHub and in every preview. The state stays in the file overnight and across sessions — strip it with Remove All Review Data before you commit; staging a file that still carries threads reminds you once. No sidecar, no database.
• Your agent as reviewer or as writer. Ask it to review a document, a folder, or only what changed since its last pass. Or leave comments yourself and send them; the agent edits the document and replies in each thread.
• Suggestions you can undo. Send as suggestions, and the agent's edits arrive as tracked changes. Accept applies one, Reject keeps your wording, and both are ordinary editor edits, so Cmd+Z takes them back.
• The Markdown Collab view, and the text editor too. The rendered document with a threads sidebar — read it, or switch to Editing and edit in place — plus dimmed markers, hovers, and a CodeLens in the plain text editor, so a reviewed file never looks corrupted.
• Any agent. Claude Code gets a plugin; Cursor, Windsurf, Codex, Copilot and the rest get the same workflow from ~/.agents/skills and AGENTS.md. Every agent changes a reviewed file with mdc, one command that keeps the comment markers intact and makes its edits through this window, so you can undo them. Comments say which agent wrote them.

Get started

1. Install the extension. Search Markdown Collab in the Extensions view, or:

   code --install-extension markdown-collab.markdown-collab-plugin
   

   Cursor, Windsurf, VSCodium, and Gitpod install it from Open VSX. A .vsix is on every GitHub release.
2. Connect an Agent…, once per machine. Cmd-Shift-P → Markdown Collab: Connect an Agent… → Claude Code. This installs the Markdown Collab plugin into Claude Code — the review workflow as /markdown-collab:review, the anchor-safe mdc helper on Claude's PATH, a guard that stops an edit that would break a comment and points Claude to the mdc command for it — and mdc makes its changes through this window, so Claude's edits arrive as edits you can undo. It installs from a marketplace the extension keeps on your machine, so the plugin always matches the extension's version: when a new version of the extension ships, it updates the plugin by itself and tells you. Restart any running Claude session afterwards, or run /reload-plugins. If Claude Code isn't found, it says so and writes nothing; set markdownCollab.claudePath if it's installed where your editor can't see it. Using Cursor, Windsurf, Codex, or Copilot instead? The same command lists them — see Other agents below.
3. Open a Markdown file and click the comment icon in its title bar. Then either click Ask agent to review, or select a passage in the rendered document, click + Add comment, write your note, and click Send.

Want to try it with no agent at all? Markdown Collab: Open Tutorial Playground writes a scratch document that arrives mid-review, with threads, a reply, and two pending suggestions to accept or reject.

Without the extension, the Claude Code plugin is also available on its own: claude plugin marketplace add ronicayu/markdown-collab-plugin, then claude plugin install markdown-collab@markdown-collab.

The loop

Comment → send → the agent edits and replies → accept → resolve.

1. Comment. Select a passage in the rendered document and write a note. The thread is written into the file, around the exact text it points at — and nothing else in the file changes.
2. Send. One button. Your agent gets your unresolved threads and the document.
3. The agent works. It edits the doc and replies in each thread with what it changed. Sent as suggestions, it proposes changes instead. The thread card shows what the agent is doing while it does it.
4. Accept or reject. A suggestion is a tracked change. Accept applies it; Reject keeps your wording; Accept all takes the whole batch after a second click.
5. Resolve when you're satisfied, or reply and go round again.

Send as suggestions, under the Send button, asks the agent to propose each change for you to accept or reject instead of making it — for that send only. Each thread card has its own Send button, and Send as suggestions in its ⋯ menu. Copy prompt is the copy button beside the Send bar.

Reviewing a colleague's PR

Open PR Review shows the Markdown a GitHub PR or GitLab MR changed, rendered, with the platform's existing comments inline — what changed and what's already been said, in one view. Add comments, reply, edit your drafts, and post them back through your gh or glab sign-in; no extra tokens.

This isn't an agent loop. There's no agent in it, and nothing gets written into the file: the comments live where they always did, on the PR or MR. It's a client for reading and answering them without leaving the editor.

Asking your agent to review

Right-click a .md file → Ask Agent to Review This Doc, or click Ask agent to review in an empty sidebar. The agent opens one thread per substantive concern: a wrong claim, an ambiguous sentence, a broken example, a contradiction with another section. It ranks concerns by severity and opens threads for the five that matter most, plus one summary thread listing everything else so you can ask for any of them ("open 3 and 7") — add "give me ten" (or more) to the focus directive to raise the cap. Pure typos and style preferences are skipped unless you ask for them. If it finds nothing, it says so instead of inventing something.

The sidebar shows "N new from Codex · M reviewed" — named after whichever agent opened them — with a Next button, and a thread counts as reviewed once you reply to or resolve it. Files over 50 KB ask for a confirmation before sending.

• Focus. The command asks for an optional one-line directive, such as "check the API examples" or "find marketing tone". Your last five are offered again.
• Standing conventions. Edit Review Conventions creates .markdown-collab/conventions.md from a template: the product's name, the house tone, the things you've decided not to care about. Every review carries it, so the agent stops re-raising what you've settled. It's capped at 4 KB per request, and the payload says so if it was cut.
• Only what changed. Ask Agent to Review What Changed sends the sections that moved since the last review and lists the threads that already exist, so a resolved concern stays resolved. The agent records a checkpoint in the file when it finishes a pass through the review tools or the mdc helper; the first review of a file is a full one.
• A whole folder. Right-click a folder, or multi-select files, → Ask Agent to Review These Docs. Every .md goes into one pass, so the agent can compare the documents against each other: terminology that drifts, a claim one file contradicts, a cross-reference that no longer resolves. Next Unread from Agent walks the results across every file.

Afterwards, Review Session Summary turns the thread state into a digest for a PR description or a note to a colleague.

Where it shows up

The Markdown Collab view. The rendered document on the left, threads on the right. It opens read-only: select a passage and comment, and the comment's two markers are written into the file's original bytes, so nothing else in the file changes and every highlight sits exactly where its markers are. Switch to Editing in the toolbar above the document to edit in place; a change rewrites only the block you typed in. The agent's edits to the file show up as they land. Comments render as Markdown. There's a find bar, a collapsible outline, optional source line numbers, and buttons to remove every resolved thread or every trace of review data in one undoable step. Mermaid and PlantUML fences and linked draw.io files render in the document. It's also in Open With… → Markdown Collab.

The text editor. Anchors are dimmed, commented text is tinted, and the threads block at the end of the file folds away. Hovering a commented passage shows its thread, with a link into the view, and one CodeLens at the top of the file gives the counts and opens the view. Select text and press Cmd+K Cmd+Alt+M to comment without leaving the editor.

Uncommitted changes. An Uncommitted Markdown tree in the Explorer lists every Markdown file that differs from HEAD. Each opens in the view with changed blocks striped, removed text shown struck through where it used to be, arrows to step between changes, and stage and unstage buttons on each row. The diff is prose against prose, so a paragraph that only gained an anchor isn't marked as changed. A file that still carries review threads shows the count in the tree, and staging it reminds you once that Remove All Review Data strips them.

How your comments reach your agent

The Send button delivers one of three ways. The first click asks, remembers your answer per workspace, and never asks again. Reset Send Mode clears it.

Type into the active terminal is the recommended, normal path: if Claude is already running in a terminal, this is picked for you without asking; otherwise the picker lists it first. The prompt goes to the terminal you're using, so start your agent there first. If nothing is running in your terminals, you're offered to copy the prompt instead. It works with any agent's terminal, not only Claude's.

Other ways to send

Headless runs are offered in the picker whenever they can work, but never chosen for you. What they need: Claude Code installed and signed in (run claude once in a terminal if you never have), a trusted workspace, and the review tool server, which starts with the extension. If claude isn't on the PATH your editor sees, set markdownCollab.claudePath. markdownCollab.headlessModel picks the model.

In this mode Claude can read files and use this extension's review tools, and nothing else: no shell, no direct file edits, no other MCP servers, and none of your Claude Code hooks. Every change lands through the editor, undoable and checked before it applies. The status bar reads Claude is reviewing guide.md · 1m 20s while it works; click it to cancel, and a run stops itself after 30 minutes. When it finishes, a notification carries the first line of Claude's report, with Show report for the whole thing and the estimated cost.

If a run can't start, the send goes to your terminal and the toast says why. If Claude Code can't load the review tools (MCP disabled by policy), headless stops being offered in that workspace until you reset the send mode.

Restricted Mode. In a workspace your editor doesn't trust, you can open the review view, read threads, add, reply to and resolve comments, and copy prompts to the clipboard. Sending to a terminal, running Claude, the review tool server, agent setup (AGENTS.md, the review skill, .mcp.json, the Claude Code plugin), the playground, the conventions editor and the Git and PR views stay off until you trust the workspace; each says so when you use it. Your workspace's conventions file isn't added to copied prompts either.

What the status bar shows

Every review request has a pulse, whichever way it was sent. Each state is something the extension observed, not a guess.

Other agents

Cursor, Windsurf, Codex, Copilot, or anything that reads project instructions:

1. Connect an Agent… → Another agent. It writes the AGENTS.md section into your workspace and installs the review skill with mdc in ~/.agents/skills/markdown-collab/ — one copy for the whole machine, which Codex, Cursor, Copilot and Windsurf all read, refreshed when the extension updates. Disconnect leaves both in place.
2. Send the comments. Set the send mode to clipboard, or pick it from the picker on your first send — the prompt goes to your clipboard instead of a terminal.
3. The agent changes the file with mdc (node ~/.agents/skills/markdown-collab/mdc.mjs …). It refuses an edit that would break a comment, and while this window is open it makes its change through the editor, so you can undo it. An agent without mdc — a colleague's, on a machine that never ran Connect — is told by AGENTS.md to ask for it rather than edit the markers by hand. docs/format.md is the full format, for reading it.

Repair Comment Anchors is the safety net if a marker breaks anyway.

Earlier versions registered the review tools with each client over MCP. Those registrations keep working; nothing new is added. Disconnect an Agent… removes one you no longer want, and the hidden Register Review Tools command still adds a .mcp.json entry for Claude Code if you want the tools there too. No token is ever written to a file you'd commit.

Keyboard

The single keys do nothing while you're typing. There's no key for accepting a suggestion on purpose: that stays a click on the card you can see.

Commands

A few commands still exist but are hidden from the palette, now that Connect an Agent… covers the everyday path: Set Up Claude Code and Register Review Tools with Claude Code (both folded into it), Start Claude Review Terminal, Copy Prompt (the clipboard send mode replaces it), and Initialize AGENTS.md.

Settings

Privacy

A plantuml fence is rendered by sending its diagram source to markdownCollab.plantuml.serverUrl — public plantuml.com by default, including when you're just viewing a colleague's PR. An http:// server sees that source in plaintext on the wire. Point the setting at your own server for anything private.

What's in your files

A thread is two anchors around the passage and one JSON line in a block at the end of the file. All of it is HTML comments.

The <!--mc:a:k7q3p-->quick brown fox<!--mc:/a:k7q3p--> jumps…

<!--mc:threads:begin-->
<!--mc:t {"id":"k7q3p","quote":"quick brown fox","status":"open","comments":[{"id":"c1","author":"ronica","ts":"2026-05-13T12:00:00Z","body":"too cliched"}]}-->
<!--mc:threads:end-->

The state stays in the file overnight and across sessions — a commit, a branch switch, a colleague opening the file, all fine. Strip it before you commit with Remove All Review Data, which clears everything in one step; staging a file that still carries threads reminds you once, in case you meant to run it first.

Under .markdown-collab/, the extension writes runtime state for the tool server and, if you create it, your conventions file. Ignore the first, commit the second:

.markdown-collab/
!.markdown-collab/conventions.md

Troubleshooting

Start with Report a Problem. It answers the first questions of any diagnosis in one paste, with tokens redacted. Then set Show Logs to Trace and reproduce: every send, tool call, refusal, and gh/glab call is logged with its outcome.

Run Claude for me isn't offered in the send-mode picker. Headless needs claude on the PATH your editor sees (or markdownCollab.claudePath), a trusted workspace (not Restricted Mode), and the tool server. The diagnostics report says which is missing.

Claude replied in the terminal, but nothing changed in the file. Claude may not have the review tools or the plugin. Run Connect an Agent… → Claude Code, and restart the Claude session.

A thread is unanchored. Its passage was deleted or rewritten beyond recognition, so the anchors went with it. Select fresh text and leave the note again, or Repair Comment Anchors if the quote still matches exactly one place.

Send did nothing. markdownCollab.sendMode has a value this version doesn't recognize. Retired modes fall back to terminal with a one-time notice; anything else falls back to ask.

Contributing

Building, the three test suites, and the release pipeline are described in CONTRIBUTING.md.

Out of scope

Real-time collaboration between people. "Collab" here means one person and an AI agent; the Markdown Collab view is not multi-user.