md-redline

Inline review comments for markdown specs, prompts, and design docs.

Highlight text in a rendered document, leave comments, and your AI agent can read and address them directly. Comments are stored as invisible HTML markers in the.mdfile itself. No sidecar files, no database, no external service. The markdown file stays the source of truth.

With the built-in MCP server, review runs in both directions. Your agent can request your review mid-task and pause until you send your feedback, or review a doc you wrote and leave anchored comments for you. Either way: no copy-paste, no context switching.

See the full review workflow in 30 seconds:

https://github.com/user-attachments/assets/3a2bf20a-d4a0-403c-b023-e877130fd959

Works withClaude Code, Claude Desktop,Codex CLI,Gemini CLI, and any other MCP client that supports stdio servers. As Sean Grove argues inspecs are the new code, specs are becoming the primary unit of work in agentic development.mdrgives that workflow review tooling closer to code review.

npm install -g md-redline mdr /path/to/spec.md # Open a file mdr /path/to/dir # Open a directory mdr --stop # Stop the running server

mdr mcp install # register with both clients (default) mdr mcp install --claude-code # just Claude Code (via claude mcp add) mdr mcp install --claude-desktop # just Claude Desktop (JSON config file)

gemini mcp add --scope user md-redline mdr mcp

{ "mcpServers": { "md-redline": { "command": "mdr", "args": ["mcp"] } } }

Prerequisite:mdrmust be on yourPATH(e.g. vianpm install -g md-redline). If your client spawns subprocesses without inheriting your shell'sPATH, use the absolute path fromwhich mdras thecommandvalue.

After installing, restart your MCP client; most clients only discover new servers at launch. To verify, ask your agent "what mdr tools do you have?" and it should listmdr_request_review,mdr_review,mdr_ask, andmdr_wait.

With MCP registered, review runs in both directions. Pick by who is giving the feedback:

The common flow right after an agent drafts a document. Tell the agent:

"Let me review docs/specs/feature-x.md in mdr before you continue."

The agent callsmdr_request_reviewand pauses. mdr opens the file, you highlight text and leave comments, then clickSend N comments. The agent receives your feedback as a structured prompt and starts addressing your comments. You can keep sending follow-up batches while it works;Send N & finishsends the last batch and closes the loop. The review is opt-in per request. The agent only pauses when you ask for it.

The reverse direction, for docs the agent did not just write: your own draft, a teammate's PRD, a spec from another repo. Tell the agent:

"Use mdr to review prd.md and leave comments."

The agent callsmdr_review. Its findings land as inline comments anchored to the exact text, and the browser opens so you can read them as they arrive. The agent then waits (viamdr_wait) while you work through the feedback: reply on any card, edit the doc, delete comments you disagree with. When you are done, clickEnd reviewin the banner. That click is the signal for the agent to re-read the file and pick up your replies and edits, so the session stays open until you press it. The agent is not stuck; it is listening.

https://github.com/user-attachments/assets/41339401-6096-40de-abbf-e93ef7ffd2c2

Some text <!-- @comment{ "id":"uuid", "anchor":"highlighted text", "text":"Rewrite this section to be clearer.", "author":"User", "timestamp":"2026-03-26T12:00:00.000Z", "replies":[] } -->highlighted text continues here.

- visible to AI agents via a plain file read
- portable with the markdown file
- invisible in normal renderers (GitHub, VS Code preview)

- Inline comments anchored to rendered text, including overlapping comments
- Two-way agent review over MCP: agents request your review, review your docs, and ask anchored questions
- Threaded replies and optionalopen/resolvedreview states
- Adjustable anchors with drag handles
- Touch and pen commenting: select with the native handles, then tap the floatingCommentbutton when done (nothing pops up while you adjust)
- Rendered, raw, and diff views
- Hand-off prompt copying for one or multiple files

- Multi-tab editing with session persistence and tab context menus
- File explorer, recent files, and native OS file picker
- Find in document (Cmd+F) with match navigation
- Table of contents with scroll spy
- Command palette (Cmd+K), keyboard shortcuts, and settings panel (Cmd+,)
- Resizable panels and right-click context menus

- Real-time reload via SSE when files change externally
- Mermaid diagram rendering with commentable text
- YAML and TOML frontmatter rendered as commentable content, not hidden
- Local image embeds and clickable links between markdown files
- Customizable comment templates
- 8 themes: Light, Dark, Sepia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

- macOS: supported
- Linux: supported; system file picker requireszenity
- Windows: supported; system file picker uses PowerShell
- Touch browsers(iPad Safari and similar): supported for reviewing and commenting; selections made by touch or pen use the floatingCommentbutton flow

By default, md-redline can read any markdown file in your home directory. The first time you runmdr(or the first time after upgrading from a version without the trusted-roots feature), your home folder is added to a trusted-roots list at~/.md-redline.json. Files outside your home directory (/tmp, mounted volumes, system paths) require an explicit permission grant via the OS folder picker the first time you open them. Granted folders are remembered across restarts.

To use the strict per-folder model instead, runmdr --restrictonce after install. This creates a~/.md-redline.jsonwith no default trust, and you'll grant each folder explicitly the first time you open a file in it.

File saves use atomic write-then-rename and mtime-based conflict detection to prevent data loss from concurrent edits. Mermaid SVG output is sanitized via DOMPurify before rendering. Only run md-redline in environments you trust.

All of these environment variables are optional.

md-redline binds to127.0.0.1and hasno authentication of any kind. That is safe today because only your own machine can reach it.

MD_REDLINE_ALLOWED_HOSTSlets you put a reverse proxy in front of it (tailscale serve, nginx, Caddy) and review from a tablet. It does not change the bind address, so the proxy still runs on the same machine. It does change the security boundary, from "my machine" to "anything that can reach the proxy".

Whatever reaches the proxy can read and write every markdown file under your trusted roots, browse those directories, see their absolute paths and your recent files, open native file pickers and reveal files in Finderon your machine, answer agent review sessions, and shut the server down. There is no login.

- Prefertailscale serve, reachable only from your own tailnet. Donotusetailscale funnel, which publishes to the open internet.
- With nginx or Caddy, terminate TLS and put authentication in front of md-redline yourself. It will not do it for you.
- Only list hostnames you actually control. The DNS-rebinding defense still holds for everything else, because an attacker's rebinding domain never matches a hostname you listed explicitly.
- Serve it over HTTPS if you can. The clipboard API the hand-off prompt copy needs only works in a secure context, so over plain HTTP that button fails on the very tablet you set this up for.

A reachable clientcannotwiden its own filesystem access: trusted roots grow only when you pick a file or folder in the native dialog, so the readable set stays whatever you approved locally.

Whether you need the variable at all depends on your proxy.tailscale serveand Caddy preserve the originalHost, so you must list the public hostname. nginx's defaultproxy_set_header Host $proxy_hostrewrites it to127.0.0.1:6373, which already passes, so you only need the variable if you forward the original host (proxy_set_header Host $host).

Turn off response buffering for/api/watch.Live file updates arrive over Server-Sent Events. md-redline sendsX-Accel-Buffering: no, which nginx honours; if your proxy ignores it, disable buffering for that path or edits will not appear until a buffer fills.

Why a hostile page cannot drive these endpoints.Every endpoint that changes something is aPOSTor aPUTrequiring a JSON content type, which a web page cannot send to another origin without the browser asking this server for permission first. That is what stops a page you visit, a link in a chat message, or an image embedded in a markdown file you are reviewing from quietly triggering an endpoint here. md-redline additionally rejects requests a browser labels cross-site, but only as a second layer: clients that send no such metadata, like the CLI and the MCP server, are deliberately unaffected.

The full surface, if you want to audit it:GET/PUT /api/file,GET /api/browse,GET /api/files,GET /api/asset,GET/PUT /api/preferences,GET /api/config,GET /api/version,GET /api/platform,POST /api/pick-file,POST /api/pick-folder,POST /api/reveal,GET /api/watch,POST /api/shutdown, and/api/review-sessions/*.POST /api/grant-accessonly re-checks a path against roots you already approved rather than adding new ones.

- The agent says it has no mdr tools.Restart your MCP client aftermdr mcp install; most clients only discover new servers at launch. For non-Claude clients, confirmmdris on thePATHthe client actually uses (see MCP setup above).
- The browser opened but the page will not load.A stale server may be holding the port. Runmdr --stop, then reopen your file.
- A review banner is stuck on screen.ClickEnd review(agent reviews) orCancel review(your reviews). Sessions do not survive a server restart, but comments do.
- Something went wrong mid-session.The file is always the source of truth. Comments and agent questions live in the markdown itself as<!-- @comment{...} -->markers, so you can read, edit, or delete them in any editor, and the agent is always told to re-read the file when a session ends unexpectedly.

git clone https://github.com/dejuknow/md-redline.git cd md-redline npm install npm run dev

Open the local URL printed by Vite (usuallyhttp://localhost:5188).

npm run dev # Start dev server npm run lint # Lint npm test # Production build + unit tests npm run test:e2e # Playwright E2E tests npm run build # Production build

The eval harness tests whether AI agents correctly read, address, and remove inline comments.

- npm run eval:dryvalidates eval fixtures
- npm run evalruns the full eval harness
- Seeeval/README.mdfor details

bin/md-redline CLI entry point (invoked as mdr or md-redline) bin/cli.js CLI implementation behind that entry point server/index.ts Hono server for file I/O, browsing, SSE, and local integrations src/App.tsx Main application shell src/components/ Viewer, sidebar, raw view, diff view, TOC, explorer, settings, etc. src/hooks/ State, persistence, selection, file watching, drag handles, tabs src/lib/comment-parser.ts Inline comment parsing and mutation helpers src/markdown/pipeline.ts Markdown rendering pipeline eval/ Eval harness for agent behavior against inline comments e2e/ Playwright end-to-end coverage

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.