Review Buddy

Review Markdown where you read it. Keep feedback attached to its passage, discuss it in threads, compare document versions, and hand work to your own agent without copying line numbers.

Review Buddy 0.1.0 targets desktop VS Code 1.102.3 or newer. Manual review needs no AI account. The optional agent workflow needs an agent with local-file/terminal access and Node.js 20.19+. Monitoring and sub-agents depend on that agent host; copying a prompt does not start either.

Right-click a saved .md file, choose Open With… → Review Buddy, select text, and press C to comment. The document-first review UI is enabled by default, with explicit Light/Dark themes. Reviews and version snapshots are stored locally in the chosen extension-host or workspace storage. See privacy and storage and support.

Why

While reading a doc you often want to leave feedback ("tighten this", "is this right?") and then have Copilot act on it. Here every comment carries its quoted text and heading path, so you can tell your agent to address the feedback through the review protocol, with its replies appearing back in the thread.

Features

• Anchored conversations — document and comments scroll independently. A single Comments control opens the pane; when it is hidden, selecting a comment opens its thread in a bounded popup. The legacy layout remains available as an opt-out setting.
• Select-to-comment — select rendered text and an add-comment glyph appears in the margin (never over the text); or press c. The composer opens in the margin, not over your content.
• Teams/Word-style cards — clearer avatars, author with date/time below, Markdown-rendered bodies with See more, threaded replies (including Copilot's), and inline Reply / Resolve / Edit / Delete (no native dialogs). Resolve/Reopen and full-thread controls sit in the card header. Expanded replies use horizontal separators and the same typography as the original comment.
• Reusable review hand-off — Copy review prompt copies a short instruction to read the review file. Its dropdown offers Copy review prompt with monitoring. Both work before any comments exist; neither freezes a count/selection nor marks comments as sent. Paste the prompt into an agent with local file/Node access; copying alone never starts an agent or a watcher. Use a sub-agent is independent of once/monitoring. Select Use as my default before copying to remember that combination for the blue primary button and copy command across documents.
• Versioned anchoring — immutable original selections plus conservative projections into later snapshots. Reliably linked passages have no status badge. The card keeps the original quote; Text changed reveals original/current wording when the passage changes. Unlocated passages have a plain-language explanation and Link to text, rather than implementation labels.
• Inline block editing — hover or select a block and press e to edit it in place with a rich WYSIWYG editor: bold shows as bold, tables edit as real grids. Cmd/Ctrl+Enter or click away to save, Esc to cancel, or use Save / Cancel in the toolbar. Edits go through VS Code undo/redo and Cmd+S; the editor closes only after the host acknowledges the edit. A rejected save leaves the draft editable with an inline explanation. The editor is lazy-loaded on first edit, so reading and commenting stay lightweight. Double-click only selects text; it never opens an editor.
• Checklist editing — task items remain real checkboxes in the editor and after saving. Checked state, nested bullet markers, uppercase [X] markers, and inline formatting survive round trips; checkbox changes participate in editor undo/redo. Intentionally escaped literal markers remain ordinary text.
• Light / Dark themes — switch using the toolbar or reviewBuddy.theme. Changes apply live across preview, comments, editing, find, code, diagrams, and rendered diff without discarding reply drafts or committing an open block edit.
• Find (⌘F) — a find bar styled like VS Code's: "X of Y" count, match-case and whole-word toggles, ↑/↓ or Enter/Shift+Enter to navigate (focus stays in the box), Esc to close.
• Version history per comment — when a change is made for a comment, a version is recorded and shown on that card as Changes (N); clicking a change opens the rendered diff scrolled to it. Versions are stored as hash-verified keyframes and deltas in a lazily-read file next to your comment store. Storage cost depends on the document and the edits, not a fixed per-version size.
• Rendered diff, side-by-side or inline — compare any two points: git refs (HEAD, Staged, Working Tree) and recorded versions, with an ADO-style Side by side / Inline toggle. The version picker includes Staged → Working copy, Committed (HEAD) → Working copy and Committed (HEAD) → Staged. Git comparisons refresh when the index or references change. Only a working-copy right side permits comment changes; staged, committed and recorded snapshots remain read-only even when their text matches the working file. Save the working document before adding or relinking an anchored comment.
• Mermaid diagrams — ```mermaid blocks render as diagrams (lazy-loaded).
• Toggle preview ↔ source — Cmd+Alt+E (Ctrl+Alt+E on Windows/Linux).

Usage

Make it the default .md editor so opening any Markdown file shows the commentable preview:

"workbench.editorAssociations": {
  "*.md": "reviewBuddy.preview"
}

Or open a single file without changing settings: right-click the file → Open With… → Review Buddy (or run Review Buddy: Open in Commentable Preview). To view it side-by-side with the source, open the source in a second editor group.

Upgrading an earlier local installation

Back up existing reviews, disable earlier local shivang.markdown-preview-comments or shivang.review-buddy installations, then reload after installing review-buddy-markdown.review-buddy-markdown. Existing global reviews remain at their original paths and are reused; workspace sidecars and document-version numbers do not change. Conflicting stores are reported without choosing or overwriting one.

Explicit reviewBuddy.* preferences take precedence; otherwise previously configured markdownComments.* values remain effective. Old commands and saved-version URI schemes remain available as compatibility aliases when the previous extension is absent. Old default-editor associations are updated without changing unrelated associations.

Adding & handing off comments

1. Save the document, select rendered text → click the margin add-comment glyph (or press c) → write → Comment.
2. Use each card to Reply / Resolve / Edit / Delete.
3. Use Copy review prompt, or its monitoring variant. The prompt points to the comment store's extension-maintained reviewInstructions: document/tool paths, current-mode rules, command argument arrays and the completion-request shape. The agent discovers current feedback at run time and processes one thread before starting the next. It must not append replies directly.

Monitoring is an explicit choice for that agent session, not a persistent flag in the JSON. The instructions require a supported watcher or bounded wait, ignore the agent's own writes, and require the agent to report if monitoring is unavailable or stops. The extension does not create an unattended agent session or install a background service.

Comment locations and visible changes

The first saved baseline is v1. Saving different Markdown creates another version. A completed Copilot iteration handles one thread and creates one version only when the saved document changed; intermediate saves between begin and complete do not create extra versions. Answer-only replies retain the existing version and have no change chip. They use a durable completion receipt, so interrupted delivery and identical retries do not duplicate replies. Numbering is per file, not per workspace or Git branch. Unsaved edits are projected for display but do not become snapshots; save before adding comments or starting an agent iteration. Copying the generic prompt is allowed while editing. Internal anchor status names and snapshot numbers are not shown as routine card badges. Location confidence is separate from whether the conversation is open/resolved or whether Copilot has addressed its feedback.

The visible version UI is the comment-attributed change history: expand Changes (N) on a card, click a change, and compare recorded versions through the rendered From/To view. These same version records carry the rendered projections and anchor metadata used internally, so there is one counter and one timeline rather than a second hidden snapshot history. New Copilot versions are attributed explicitly to their one iteration thread; arbitrary manual edits are no longer assigned to comments from timing or proximity guesses. Change rows show the version and label. Exact time and older inferred/shared attribution remain available in hover and keyboard-accessible descriptions, without the prominent "likely" / "also for" badges. Changes starts collapsed in pane, popup and full-thread views, while retaining deliberate expansion choices. Diff revision labels occupy a separate, clipped row instead of overlapping the controls. The controls wrap in compact windows and version menus stay inside the viewport. Diff changes use red/green fills and word highlights, not vertical change rails or extra rail padding. Native Markdown blockquote styling is retained and explicitly themed in all three document surfaces.

Diff and review actions share one full-width toolbar: comparison/navigation controls on the left, review actions on the right. Comment navigation and the resolved filter live with the comments pane. Version labels are compact; timestamps remain available on hover. Opening a change selects its predecessor/result pair in both the content and picker instead of displaying "All Changes."

Original/current quote excerpts are limited to three lines each and use the full card width, including hidden-pane popups. Open full comparison uses the recorded original and displayed/current version; unavailable original snapshots are not fabricated. The original quote remains available in the full thread.

The bottom hint strip shows available shortcuts: C comments on selected text, E edits a hovered/selected block in the normal preview, and F focuses the active thread. Esc closes the focused thread. Typing fields retain normal text entry and Ctrl/Cmd+F remains Find. Web links use the system opener; local Markdown references open in the commentable preview, and heading references navigate to stable, duplicate-safe heading IDs. Executable link schemes such as javascript: and command: are not supported.

Each anchor retains its original version, selected quote, and half-open UTF-16 range in the rendered-text projection. Its current range, current quote, and status are calculated across versions. Every version reconstructs both raw Markdown and the exact canonical rendered projection; rendered offsets are deliberately not presented as source line/column coordinates. A thread's open/resolved state is independent of its anchor status. Older stores can import uniquely matching quotes into v1; that is an imported baseline, not a reconstruction of their unavailable original document. Unidentifiable legacy locations remain unverified. Outdated/ambiguous locations never fall back to fuzzy matching in the versioned preview. Large diffs are partitioned at unique, order-stable lines and words before bounded character alignment, so an unrelated rewrite does not invalidate every comment. Duplicate landmarks are not tie-broken arbitrarily. A uniquely matched quote with a certified interior also keeps repeated boundary punctuation from absorbing an appended sentence.

Repairing a comment's location

If the extension cannot confidently locate a passage, use Link to text, select its intended passage in the saved current document, then confirm. Change linked text in the comment's actions menu also allows correcting an existing link. Escape/Cancel abandons the selection; document editing is suspended while choosing the new location.

Relinking changes attachment metadata only: it preserves the original quote, conversation, timestamps and first verified origin, records an audit entry, and does not create a document version. A previously unverified comment does not acquire fabricated original context. A changed document/conversation, stale selection or pending agent iteration rejects the operation explicitly. An interrupted delivery can be retried safely.

The repair is new user feedback for pending; the next Copilot response records which location revision it addressed, preventing repeated processing of the same repair. The begin response includes the verified current location, so an agent need not guess from an old quote.

Saved-version comparisons use attachment locations for that revision rather than projecting the latest missing location backwards. Older comparisons remain read-only and offer Open current document when a location needs attention. A comment created later is identified as such. New history records maintain compact location deltas; pruning carries them forward. Older histories are reconstructed conservatively, and missing intermediate evidence never authorizes a fuzzy guess. Intentional deletion does not force relinking: the conversation can still be discussed or resolved.

The extension does not launch an AI agent by itself. The copied prompt asks Copilot to use the bundled dist/iteration.js tool (Node.js required):

node <iteration.js> pending --document <file> --store <comments.json>
node <iteration.js> begin --document <file> --store <comments.json> --expected-hash <fresh-sha256> --threads <one-id> --intent-policy document
node <iteration.js> hash --document <file>
node <iteration.js> complete --document <file> --store <comments.json> --request <request.json>

The completion request contains iterationId, the final saved file's expectedHash, and replies: [{ "commentId": "...", "body": "..." }], containing exactly the one iteration thread. That thread gets one reply with iterationId, baseVersion, version, and a UTC timestamp; parent updatedAt is unchanged. An identical completion retry does not duplicate a version or reply. Review iterations honor the stored document Agent/Ask mode, regardless of old per-thread intent; classic handoffs use --intent-policy per-comment. A mode change during an iteration rejects completion. After completion, discover pending feedback and the current hash again before starting another thread. pending is read-only and excludes resolved or already-answered threads unless new user feedback has arrived.

The tool persists snapshots even with the preview or VS Code closed. Without this protocol, external replies are displayed but do not create duplicate versions or infer comment ownership: missed intermediate file states cannot be recovered. The extension cannot attribute arbitrary disk writes to Copilot; begin/complete define that boundary explicitly.

Stale hashes, changed/resolved/deleted selected threads, overlapping iterations, or conflicting retries fail explicitly and leave data intact. Cancel Pending Copilot Iteration (also available in the preview) abandons a pending iteration and checkpoints any saved partial edits. It does not undo edits. Re-read the document and pending feedback after cancellation; the generic prompt itself is reusable. If a new comment is rejected because its selection is stale or storage is busy, the composer keeps the draft; closing it and selecting text again restores that draft rather than losing it.

Storage

By default comments are stored machine-locally in the extension's storage (keyed by the file's path), keeping your workspace clean — they are personal to your machine and not shared via git. Prefer to share them with a repo? Set the location to workspace and they live in a sidecar file next to the document (<file>.md.comments.json). Comments and history follow explicit VS Code file renames. External filesystem renames cannot be identified reliably; move both stores deliberately instead of relying on same-content guesses. Complete/cancel an iteration before renaming its file because copied prompts contain its original absolute paths.

One unified history file lives beside the comment store as .versions.json (schema v4). It stores periodic keyframes plus compact line deltas for both raw Markdown and canonical rendered projections, with SHA-256 verification for each reconstructed value. The same records contain anchor metadata, attribution, guarded iteration provenance, reply-only completion receipts, historical location deltas and explicit attachment audit/delivery records. Existing v1/v2/v3 histories remain readable; the next mutation writes v4 without renumbering or discarding old snapshots. Back up stores before upgrading; older extension builds must not write the upgraded history. Comment stores remain schema v3, with additive reviewInstructions and locationRevision metadata; replies may record the location revision they addressed.

Anchor-origin, completion-receipt and pending-iteration base versions are pinned and never pruned. Other old versions are retained up to the 500-version / 2 MiB navigation caps; pruning rebases surviving raw and projection chains into keyframes. A single document or projection above 64 MiB fails explicitly.

History writes use unique temporary files and an exclusive .versions.json.lock. Every mutation re-reads the latest file inside the lock so editor and diff sessions cannot overwrite each other. Interrupted reply delivery is journaled and retried on the next checkpoint/completion. Existing .versions.json diff history and <comments.json>.history.json anchor history are merged transactionally on first use; the old anchor file is renamed .migrated only after the unified file is durable.

The comment store is a small JSON document (schema v3):

{
  "version": 3,
  "document": "design-notes.md",
  "comments": [
    {
      "id": "c_ab12cd",
      "quote": "under two minutes",
      "prefix": "aha\" moment in ",
      "suffix": ".",
      "headingPath": ["Overview"],
      "author": "you",
      "status": "open",
      "createdAt": "2026-07-10T00:00:00.000Z",
      "updatedAt": "2026-07-10T00:00:00.000Z",
      "replies": [
        { "author": "you", "body": "Can we make this the headline metric?", "createdAt": "2026-07-10T00:00:00.000Z" },
        { "author": "copilot", "body": "Yes — added.", "createdAt": "2026-07-10T00:06:00.000Z" }
      ]
    }
  ]
}

The example omits generated reviewInstructions for brevity. In v3 the root message is replies[0]; legacy v1/v2 root bodies are still read correctly. Existing copiedAt and attribution metadata are preserved, but no longer used to present a misleading "Sent" state.

Settings

Experimental document-first review UI

The document-first design is enabled by default. Its compatibility setting is:

"reviewBuddy.experimental.reviewUi": true

It provides independently scrolling document/comments regions, self-contained thread cards with per-thread reply boxes, and one document-wide Agent / Ask selector (Agent by default). Clicking a card locates its passage without moving the comments pane. The two rendered-diff document columns remain linked. Light remains the default even in a dark editor theme; choosing Dark is explicit.

Comment navigation and Find reveal the actual quoted/matched text, including passages near the end of long paragraphs and inside horizontally scrolling tables. Diff scroll position survives realignment and working-document refreshes, including large inserted/deleted regions. With Comments hidden, clicking a highlight opens a viewport-bounded thread popup. It shifts upward near the bottom edge; long threads scroll internally so replies and actions stay reachable. Thread popups and new-comment composers adapt to window resizing without clearing drafts. The popup uses the same card renderer as the pane and includes the same Resolve and full-thread controls. Replies start collapsed in both the pane and hidden-pane popup, with an expandable reply count; your explicit per-thread expansion choice is remembered. The popup keeps the original comment fully readable, and Open in full view still displays all replies. Comments is the rightmost toolbar control. Bulk selection has been removed; individual comment/reply deletion remains available. Quoted context and actions share one compact header rather than separate rows. Resolve's icon and label turn green on hover without a filled background; the Agent/Ask menu matches its button's width.

The Agent/Ask dropdown is an accessible in-preview menu with keyboard navigation, a selected-item indicator and a keyboard-only focus ring, rather than a browser/OS select popup.

Preview colour sources

Light and Dark are based on VS Code's built-in Light Modern / Dark Modern colour pairs, independent of the surrounding editor theme. Values were verified against theme-defaults/themes/light_modern.json and dark_modern.json, and the native markdown-language-features/media/markdown.css and highlight.css. Fenced syntax uses the installed Visual Studio highlight styles with the native preview's token overrides.

Both foreground and background are explicit. This prevents VS Code's injected opposite-theme inline code colour from leaking onto the preview's selected theme.

Document mode and drafts

In-place editing validates complete Markdown block boundaries before applying or relocating an edit. It cannot retarget a stale paragraph onto matching text inside a heading, fence, or table fragment. Wide-table editing preserves GFM column alignment, reveals the selected cell, and provides mouse- and keyboard-operable Rows/Columns/Move controls. Diff document editing remains disabled; commenting and replies remain available.

Document mode is saved as optional documentIntent metadata in the comment store. The new UI's copy prompt uses it for every selected thread, without rewriting old per-comment intents or timestamps. Turning the feature off preserves the classic per-comment behavior. Invalid stored mode metadata requires an explicit Agent/Ask choice before copying; it never silently becomes Agent. Changing the selector does not run an agent or copy anything automatically.

Unsent drafts and selected-thread state can follow the document between open review views. They use the VS Code webview-state/host bridge, not the Copilot comment store. Focus, modal state, and viewport layout remain local to each view. Older persisted bulk-selection fields are discarded without clearing drafts or expansion state.

Development

Before changing UI, read the UI instructions. They define the shared design language, component ownership, interaction rules and visual checks for all contributors, including parallel feature branches.

npm install
npm run build          # bundle extension + webview (esbuild); copies codicons + mermaid
npm run test:unit      # Node/jsdom unit tests (pure logic + DOM logic)
npm run test:history   # focused history, anchoring, persistence, and review UI coverage
npm run test:webview   # builds, then runs the real-Chromium e2e harnesses
npm test               # isolated native VS Code UI + real-store/edit/undo integration tests

# package + install into VS Code (build runs automatically via vscode:prepublish):
rm -f *.vsix && npx --yes @vscode/vsce package --allow-missing-repository --skip-license
code --install-extension review-buddy-markdown-0.1.0.vsix --force   # then reload the window

Press F5 in VS Code to launch an Extension Development Host and try it live. Set VSCODE_EXECUTABLE_PATH to the installed VS Code Insiders executable to run integration tests there rather than downloading stable VS Code. VSCODE_TEST_USER_DATA selects an isolated test profile.

On managed machines where package-manager/registry access is prohibited, use existing dependencies and direct binaries (node esbuild.js, ./node_modules/.bin/tsc) rather than the installer commands. The review launchers below never install packages or download an editor.

Architecture

Two layers; only the extension host touches disk, the webview talks via postMessage.

• Host: src/extension.ts (activate/commands), src/editorProvider.ts (CustomTextEditorProvider — the only surface, opens .md as the preview), src/webviewHost.ts (CommentSession), src/webviewHtml.ts (one production preview/diff HTML builder), src/store/ (CommentStore abstraction: fileStore.ts, factory.ts, keying.ts), src/sidecar.ts (store file I/O + migration), src/render.ts (markdown-it → HTML, source-line mapping, mermaid emit), src/prompt.ts (Copilot prompt + delta), src/documentMode.ts (mode compatibility), src/reviewState.ts (acknowledged shared draft patches), src/anchor.ts (text-quote anchoring + bounded fuzzy), src/blockSource.ts (block↔line mapping + edit plan), src/find/search.ts, src/types.ts.
• History: src/history/ provides unified raw/rendered keyframe-delta history, anchor mapping, attribution, guarded iteration provenance, and the independent iteration CLI. src/versionView.ts exposes read-only virtual documents and native version comparison. The extension API exposes openVersionPair and showOriginalVersion for consumers using the same history model.
• Webview: src/webview/ — main.ts (orchestrator), layout.ts (gutter collision + responsive mode), gutter.ts (margin cards), card.ts (card component), commentBody.ts (safe Markdown render), sidebar.ts (panel), dom.ts (text-map + CSS Highlight-API paint + hit-testing), find.ts, blockEdit.ts + pm*.ts (ProseMirror block editor, lazy), tokens.css + styles.css. The default review UI uses reviewLayout.ts, reviewCard.ts, reviewUi.ts and the gated reviewTokens.css / reviewBase.css / review.css sheets in that same bundle.
• Build: esbuild.js → dist/extension.js, dist/webview.js, dist/webview.css, dist/blockeditor.js (lazy), dist/iteration.js (standalone Node CLI), and copies dist/mermaid.min.js (lazy) + dist/codicon.{css,ttf}.

Testing

• Unit (test/*.test.ts, Node --test + jsdom): pure logic and DOM logic.
• Browser e2e (scripts/*-e2e.cjs, playwright-core via installed Edge/Chrome): loads the actual bundled dist/webview.js and drives real gestures under the production CSP. These exist because VS Code webviews are opaque to the OS accessibility tree — UI automation can't drag-select or double-click inside them, so webview interactions are verified here.
• Integration (@vscode/test-electron): an isolated editor profile exercises production UI code inside a real webview, real temporary comment/history files, live file updates, document mode, draft sharing, in-place edits, WorkspaceEdit/undo/redo, closed-preview iteration completion, and native immutable version documents/diff tabs. A test-only driver is compiled to a temporary location; no test command/eval API is shipped in the extension.

The large fixture is a synthetic README of approximately 330 KB and 11,000 lines. The history suite covers large rewrites, insertion boundaries, deletion, duplicate blocks, heading changes, formatting, code fences, Unicode, multi-block selections, and restoring deleted text. The browser suites use an installed browser (Edge on Windows); MPC_CHROMIUM_EXECUTABLE overrides discovery. Browsers are closed on success and failure rather than left running after a failed assertion.

scripts/copilot-iteration-scenario.cjs provides an opt-in real Copilot trial. Run prepare with a new absolute artifact directory, submit 01-ask.prompt.txt to Copilot, then run after-ask, submit 02-update.prompt.txt, run after-update, submit 03-followup.prompt.txt, and run verify. It checks exact file changes, unchanged parent timestamps, preserved original anchors, and one version per iteration. Ordinary tests never invoke a paid model automatically.

For the live external-iteration integration case, set MPC_LIVE_REVIEW_DIR to a trial awaiting its third prompt before running npm test. The isolated preview writes live-ready.json; run the third Copilot prompt only after that signal. The test checks the pending indicator and the new reply/version appearing without a manual refresh. MPC_CAPTURE_INSIDE=1 enables a local debugging connection for scripts/capture-insiders.cjs; the capture attaches to the existing isolated window, not another browser window. The test runner closes its window afterward.

Design docs and decisions live in design/ (see design/decisions-log.md). Reinstalling a VSIX does not update already-open windows — reload the window to pick up a new build.

UI design workbench

Run node scripts/review-workbench.cjs and open the printed loopback URL. It builds and serves the same production UI assets and HTML as VS Code, with an isolated memory-backed host. There are no alternate card/layout implementations or prototype-only CSS overrides. UI refinements happen once. The workbench does not modify your real documents, comments, or installed extension.

Run node scripts/review-devhost.cjs to open an isolated real VS Code development host with the feature enabled and the same sample document/comments. It uses a cached editor (or VSCODE_EXECUTABLE_PATH), never downloads one, and preserves the sample/profile under .vscode-test/review-devhost/. Your normal VS Code profile and installed extension are unchanged. This isolated profile does not copy your existing global comment stores.

For native integration tests, set VSCODE_EXECUTABLE_PATH to an existing VS Code executable when downloads are not permitted, then run node out/test/runTest.js after compiling/building. This runner creates and removes its own temporary profile. Set MPC_NATIVE_SHOTS to an output directory to also capture the actual isolated VS Code window's light preview/diff and light/dark editor states. This optional test-only capture enables a loopback debugging port for that disposable profile; neither the production extension nor the normal development launcher exposes a debugging endpoint.

See the design brief and preserved-feature inventory and integration contract for scope and verification.

License

MIT — see LICENSE.