{"slug": "cli-tool-for-reviewing-markdown-files-with-inline-comments", "title": "CLI tool for reviewing Markdown files with inline comments", "summary": "A new open-source CLI tool called md-review-plus enables AI agents and humans to collaboratively review Markdown files, code diffs, and HTML artifacts with inline comments, drag-and-drop prioritization, and encrypted remote relay. The tool provides structured feedback for agents to act on and supports multiple review templates for different use cases.", "body_md": "A collaboration runtime for AI agents and humans.Your agent generates a markdown doc, a code diff, a design exploration, a prioritization board — and pipes it through`md-review-plus`\n\nfor the human to actuallyinteractwith. The reviewer drags, picks, approves, comments, and asks questions. Structured feedback comes back on stdout for the agent to act on.\n\nEnd-to-end encrypted. Open source. Self-hostable. Works locally or over the relay for SSH / mobile / cloud-CC use cases.\n\nMost CLI review tools dump prose at you and ask \"looks good?\". Markdown\nprose review is *one* surface; the value compounds when reviewing also means\n**choosing between rendered variants**, **anchoring feedback to a line**,\n**dragging cards into priority columns**, or **tuning sliders against a live\npreview**. None of that fits in a markdown buffer.\n\n`md-review-plus`\n\nships:\n\n- the classic per-\n`##`\n\n-section markdown reviewer (with inline text-range comments) - a\nthat turns any single-file HTML artifact into a review surface`window.mdrp`\n\nshim **8 templates** Claude can fill in for the common review shapes (variant pick, code diff, prioritization, page-styling tuner, design-system review, …)- a\n**bidirectional Q&A loop**— reviewers can ask the agent questions, the agent must answer next round that ships either format over an end-to-end-encrypted relay so the reviewer can be on a different device/network than the CLI`--remote`\n\nmode\n\n```\nnpm install -g md-review-plus\nmd-review-plus install --skills [--global]   # install the Claude Code skill + templates\n```\n\n`install --skills`\n\ndrops the skill at `~/.claude/skills/md-review-plus/`\n\n(with\n`--global`\n\n) or `.claude/skills/md-review-plus/`\n\n(project-local), and copies\nall eight templates next to it so Claude can grab one and fill it in.\n\n```\nmd-review-plus README.md --review             # markdown review, local browser\nmd-review-plus README.md --review --remote    # markdown review, encrypted relay URL\nmd-review-plus tuner.html --review            # HTML artifact review, local browser\nmd-review-plus tuner.html --review --remote   # HTML artifact, encrypted relay URL\n```\n\n`--review`\n\nblocks the CLI until the reviewer hits Submit; the structured\nfeedback is printed to stdout, then the CLI exits.\n\nExit codes: `0`\n\n= review submitted, `1`\n\n= browser closed without submitting or\nsession expired.\n\n| Use case | File | Mode |\n|---|---|---|\n| Prose / spec / plan / linear narrative | `*.md` |\nMarkdown reviewer |\n| Code / patch / diff review with per-line comments | `*.html` |\n`pr-review` template |\n| \"Which of these do you prefer?\" (variants, copy, layouts) | `*.html` |\n`design-grid` template |\n| Prioritization / ranking / what-ships-first | `*.html` |\n`priority-board` template |\n| Page-level live styling review (sliders → live preview) | `*.html` |\n`style-review` template |\n| Design system / token review | `*.html` |\n`design-kit` template |\n| Tuning sliders/knobs against a single component | `*.html` |\n`design-tuner` template |\n| Schema-driven config form | `*.html` |\n`config-editor` template |\n| Concept-map / graph annotation | `*.html` |\n`concept-map` template |\n| Basic section-card layout for arbitrary HTML content | `*.html` |\n`review-doc` template |\n\nMode is inferred from the file extension. The markdown path is the classic v1.3 reviewer with full per-section approve/reject + inline text-range comments. HTML files go through the sandboxed artifact runtime described next.\n\nEvery `.html`\n\nartifact renders inside an `<iframe sandbox=\"allow-scripts\">`\n\nwith a strict CSP. The host page injects a tiny `window.mdrp`\n\nshim so the\nartifact can talk back to the review surface:\n\n```\nwindow.mdrp.ready({ title, chrome: 'host' | 'none', sections: [{id, heading}] });\nwindow.mdrp.setSectionStatus(id, 'approved' | 'rejected' | 'pending');\nwindow.mdrp.addComment({ sectionId, anchor?, text });\nwindow.mdrp.addReaction({ targetId, emoji });    // 👍 👎 🤔 ❤️ 🎉 — per target\nwindow.mdrp.askQuestion({ sectionId?, text });   // questions for the agent\nwindow.mdrp.update(state);                        // arbitrary interactive state\nwindow.mdrp.submit(stateOrNull);                  // optional artifact-driven submit\n```\n\nThe shim is the only exit. The iframe can't `fetch`\n\n, can't load external\nscripts, can't escape the sandbox. See the **Security model** section below.\n\nAfter `md-review-plus install --skills`\n\n, the templates ship to\n`~/.claude/skills/md-review-plus/templates/`\n\n. Each is a self-contained\nsingle-file HTML artifact with a `TEMPLATE_DATA`\n\nconstant the agent fills\nin. Header comment at the top of each file documents the fillins.\n\n| Template | Best for |\n|---|---|\n`design-grid.html` |\nCompare N rendered variants. Per-variant reactions, comment, ask-a-question, pin-to-element notes, winner radio |\n`pr-review.html` |\nMulti-file unified diff. Per-hunk approve/reject + severity tag + reactions. Per-line comments OR inline suggested edits |\n`priority-board.html` |\nDrag cards between Now / Next / Later / Cut. Editable titles, effort/impact chips, per-card comment + ask |\n`style-review.html` |\nPage-level styling review. Sliders/pickers for colors, type, spacing, radius drive a live preview via CSS variables. Click-to-pin element notes |\n`design-kit.html` |\nHolistic design-system review. Palette, type ramp, spacing, radii, shadows, components — all driven by global tokens |\n`design-tuner.html` |\nSingle-component playground: sliders + live preview, apply to submit |\n`config-editor.html` |\nSchema-driven form with typed fields and inline validation |\n`concept-map.html` |\nSVG concept map; each node is a section, click to annotate |\n`review-doc.html` |\nGeneric section-card layout for arbitrary HTML content |\n\nStatic screenshots of the four \"rich\" templates are in\n[ docs/](/Seiraiyu/md-review-plus/blob/main/docs):\n\n[design-grid](/Seiraiyu/md-review-plus/blob/main/docs/design-grid.png),\n\n[pr-review](/Seiraiyu/md-review-plus/blob/main/docs/pr-review.png),\n\n[priority-board](/Seiraiyu/md-review-plus/blob/main/docs/priority-board.png),\n\n[style-review](/Seiraiyu/md-review-plus/blob/main/docs/style-review.png),\n\n[design-kit](/Seiraiyu/md-review-plus/blob/main/docs/design-kit.png).\n\nWhen the reviewer hits Submit, the CLI emits a structured markdown report. Each block appears only when there's something to report:\n\n```\n## Needs Changes            — rejected sections + their comments\n## Section Comments         — comments on approved/pending sections\n## Line Comments            — per-line anchored notes; SUGGEST: … blocks are inline edit suggestions\n## Approved                 — list of approved sections\n## Open Questions           — questions the reviewer wants the agent to answer\n## Reactions                — per-target emoji counts, e.g. **v2**: 👍×3 🎉\n## Interactive State        — JSON state the artifact submitted (rankings, tuned values, picked winners)\n```\n\nThe agent reads this, applies changes, answers the questions, and optionally re-runs the review with the updated artifact.\n\nFor SSH / cloud / mobile / Claude-Desktop-on-iPad cases the local\nbrowser isn't reachable. Add `--remote`\n\n:\n\n```\nmd-review-plus ./document.md --review --remote\nmd-review-plus ./tuner.html --review --remote\n```\n\nThe CLI:\n\n- encrypts the document with a fresh AES-256-GCM key\n- uploads the ciphertext to the relay\n- prints a URL with the key in the URL\n**fragment**(browsers do not send fragments to the server)\n\nThe reviewer opens the URL on any device, the browser decrypts the ciphertext locally, the review happens, the reviewer submits, the CLI receives encrypted feedback, decrypts it locally, and prints the structured report to stdout — same exit-code contract as local mode.\n\nOverride the relay with `MDRP_RELAY`\n\nor `--relay <url>`\n\n. Self-host\ninstructions: [relay/README.md](/Seiraiyu/md-review-plus/blob/main/relay/README.md), [relay/DEPLOY.md](/Seiraiyu/md-review-plus/blob/main/relay/DEPLOY.md).\n\n**Privacy:** AES-256-GCM end-to-end. The key never leaves the CLI or\nthe reviewer's browser. The relay holds ciphertext for up to 24h,\ndeletes on submit, and does not log request bodies or URL fragments.\n\n```\nmd-review-plus install --skills [--global]\n```\n\nThe shipped skill teaches Claude:\n\n- When to use markdown review vs HTML mode (decision table)\n- Which template to pick for which review shape\n- That open questions in\n`## Open Questions`\n\nare blocking — answer them in the next response - How to surface the\n`--remote`\n\nURL on the first line of the reply (so the human sees it even if the agent's response is long)\n\nOnce installed, just say *\"please review this remotely\"* and Claude\npicks a template, fills it in, runs `--review --remote`\n\n, and surfaces\nthe URL.\n\nHTML artifacts run with these hardening defaults:\n\n`<iframe sandbox=\"allow-scripts\">`\n\n—*no*`allow-same-origin`\n\n, so the iframe is a separate origin from the host page and can't reach into the host's DOM- Inline CSP:\n`default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; font-src data:;`\n\nIn plain English, an HTML artifact cannot:\n\n- make\n`fetch`\n\n/`XHR`\n\n/ WebSocket calls — the relay never sees plaintext, but neither would*any*network endpoint - load remote scripts, stylesheets, fonts, or images\n- navigate the parent page or submit forms across origins\n- read or write the host page's DOM\n\nThe only exit is `parent.postMessage(...)`\n\nfrom the injected shim. Combined\nwith the E2E encryption in `--remote`\n\n, this means even a malicious\ntemplate would have no way to exfiltrate the document being reviewed.\n\nfor HTML artifacts (the formatter only runs on the local server path). Extract`--remote`\n\nstdout is currently raw JSON`formatFeedback`\n\nto a shared module so`RemoteModeApp`\n\ncan format client-side. ~30 lines.**No cross-iframe text-selection comments** for HTML artifacts yet. Markdown reviews have this via`SelectionPopover`\n\n; HTML needs a shim API for the iframe to expose selection events.**Bulk Approve/Reject doesn't fit every template**(pr-review, design- grid, priority-board own their own semantics). Templates need a way to opt out of the host's bulk controls.(fixed in 1.4.1)doesn't handle the`lineComments[].startLine`\n\nparser`line:<hunkId>:<n>`\n\nanchor format — falls back to`0`\n\n.\n\n`md-review-plus`\n\nis a fork of\n[ md-review](https://github.com/ryo-manba/md-review) by Ryo Matsukawa.\nThanks for the foundation.", "url": "https://wpnews.pro/news/cli-tool-for-reviewing-markdown-files-with-inline-comments", "canonical_source": "https://github.com/Seiraiyu/md-review-plus", "published_at": "2026-07-15 05:29:03+00:00", "updated_at": "2026-07-15 05:47:57.439944+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["md-review-plus", "Claude"], "alternates": {"html": "https://wpnews.pro/news/cli-tool-for-reviewing-markdown-files-with-inline-comments", "markdown": "https://wpnews.pro/news/cli-tool-for-reviewing-markdown-files-with-inline-comments.md", "text": "https://wpnews.pro/news/cli-tool-for-reviewing-markdown-files-with-inline-comments.txt", "jsonld": "https://wpnews.pro/news/cli-tool-for-reviewing-markdown-files-with-inline-comments.jsonld"}}