Coding agents draft specs, architecture docs, changelogs, and README updates in seconds — but a human still has to judge the quality of all that output.

The bottleneck shift

A year ago, the typical workflow was: you write a spec, you get comments, you revise, then you implement and get code review. Humans did most of the writing and coding. Now, agents produce first drafts of design docs, API references, runbooks, and onboarding guides — and they do it in seconds.

Code implementation and code review can now be handled by agents, so those are no longer the bottleneck. What surfaced instead is the step right before: document review. A human has to read 2,000 lines of generated markdown and decide what's wrong. The writing part got dramatically faster. LLMs can assist with document review too, but compared to code implementation and code review, the human judgment required is still larger.

This asymmetry compounds fast. Every agent-assisted project now has a stack of "needs human review" documents growing in a shared folder. If you're running multiple agent loops in parallel — one for the spec, one for the implementation plan, one for the test strategy — review becomes a pipeline stall. GitHub PRs remain the right tool when you need third-party review. But the step before that — the fast local self-review loop where you and your agent iterate on a draft — doesn't belong in a PR. Branching, diffing, and assigning reviewers is a lot of process for a first draft the agent wrote in seconds.

Why prose feedback is lossy

The most common workaround today is to have the agent read the document and then fix things based on natural-language feedback:

"The error handling in section 3.2 is too vague — be specific about what happens on timeout."

This looks reasonable. The agent reads it, searches for something about error handling, and makes a change. But several things go wrong:

Position is ambiguous. If section 3.2 has three paragraphs about error handling, which one did the reviewer mean? The agent guesses, and sometimes guesses wrong.

Context is lost. The reviewer was looking at a rendered document — they saw the Mermaid diagram, the table layout, the code blocks with syntax highlighting. The prose feedback carries none of that visual context.

Round-trips are vague. The agent applies a fix. Did it address the right spot? The reviewer pastes the updated draft back into the chat. No diff. No anchoring. Another round of guessing.

The fundamental problem: prose feedback loses the structure the reviewer had in mind. The reviewer knows which text range they're commenting on — but that spatial information is discarded the moment they express it in natural language.

Feedback as a machine-readable artifact

What if the reviewer's comments came back as structured JSON, with every comment anchored to a precise location in the source markdown?

That's what MDXG Redline (online demo) produces. The reviewer selects any text range in a rendered markdown document, leaves an inline comment, and on export the tool writes a JSON file like this:

{
  "document": "api-spec.md",
  "docHash": "a1b2c3d4e5f6a7b8",
  "exportedAt": "2026-06-15T10:30:00.000Z",
  "comments": [
    {
      "id": "f3a1c8b2",
      "quote": "The service retries up to 3 times",
      "comment": "Specify the backoff strategy — is it exponential? Fixed interval? This matters for downstream timeout config.",
      "headingPath": ["## 3. Error Handling", "### 3.2 Retry Policy"],
      "sourceLine": 142,
      "created": "2026-06-15T10:28:11.000Z"
    }
  ]
}

Every comment carries:

• quote — the exact text the reviewer selected (human-readable reference)
• comment — what the reviewer wrote
• headingPath — the heading ancestry, from shallowest to deepest (["## 3. Error Handling", "### 3.2 Retry Policy"]), so the agent can navigate the document hierarchy
• sourceLine — the 1-origin line number in the source markdown, so the agent can jump straight to the right spot

(The actual export also includes blockId, startOffset, and endOffset — internal anchoring fields used for round-trip re-import into the next review round. The four fields above are the ones your agent needs.)

No guessing, no ambiguity. The agent reads the JSON, opens the source file, goes to line 142, and applies the feedback directly. The feedback JSON is a plain file on disk — any agent that can read JSON and edit files can consume it, regardless of framework or provider.

The loop in practice

MDXG Redline is designed around a review loop where an agent and a human pass a document back and forth:

1. The agent uses the CLI to generate a <name>-<hash>-review.html file from the markdown — a self-contained HTML file that renders the document with syntax highlighting, diagrams, and math.
2. The CLI auto-launches the reviewer's browser.
3. The reviewer reads the rendered document, selects text ranges, and leaves inline comments. One click writes <name>-<hash>-feedback.json to the same folder.
4. The agent monitors in the background, automatically picks up the JSON, and applies the feedback.

Each revision gets a unique hash in the filename, so review/feedback pairs for different revisions never collide.

For Claude Code and Codex users, there's a md-review skill that automates the entire loop — HTML generation, waiting for feedback, and applying revisions:

# install the skill
gh skill install oubakiou/mdxg-redline md-review --agent claude-code --scope project

# then just tell the agent:
# "please request a review for spec.md"
# or invoke the slash command directly:
# /md-review README.md

The skill is a convenience wrapper. Since the feedback JSON is a plain file, the loop works with any agent — you can wire it into a custom LangChain pipeline or a simple shell script that polls for the JSON.

What it renders

MDXG Redline isn't just a review overlay — it's a markdown rendering engine packed into a single standalone HTML file with no backend and no dependencies.

Smartphone support — On mobile screens, the UI switches to a layout with a footer bar for TOC, Comments, and Search. You can review and comment from your phone — no need to wait until you're back at your desk.

Syntax highlighting for ~235 languages — The CLI auto-detects which languages your document uses and injects only those Shiki grammars, keeping the file lean.

Mermaid diagrams and KaTeX math — Fenced `mermaid blocks render as SVGs; $...$ / $$...$$ math renders via KaTeX. Both are auto-detected and injected only when present.

Word-style stacked pages — The document splits at H1/H2 boundaries into paper-like sheets you scroll through vertically, with a sidebar for navigation. Footnotes and left-hand keyboard navigation are also built in.

See the full feature list in the README for details.

Try it in 30 seconds

No install needed — open mkdn.review and load any public GitHub raw URL. Here's a one-click example that loads the project's own README:

Select any text in the rendered document, leave a comment, and click "Copy as JSON" to see the structured output.

Want to try with your own project? Just replace the URL: mkdn.review/?url=<your-github-raw-url>.

Local review — if you have Node.js:

`bash
npx mdxg-redline your-draft.md
`

This generates a review HTML in the same directory and opens it in your browser. The generated file is fully self-contained — you can email it, drop it in Slack, or put it in a shared folder. Everything stays local; no content or comments are sent anywhere.

Privacy note: The standalone and CLI builds enforce connect-src 'none' via CSP — your document body and comments cannot leave the browser. The online version (mkdn.review) likewise never sends your content or comments anywhere — the only network request is the ?url= fetch, which retrieves public raw content from a short allowlist (GitHub raw, Gist raw).

It's an MDXG implementation

MDXG Redline is a third-party implementation of the Markdown Experience Guidelines (MDXG) by Vercel Labs — the read-only Viewer rendering profile, with a review layer (inline commenting + structured JSON export) added on top. See the compliance table for details.

MDXG Redline is MIT-licensed and fully open source. If reviewing agent-generated documents is a bottleneck in your workflow, give it a try:

• Try the online viewer →
• GitHub repo →
• npm → npx mdxg-redline draft.md
• Claude Code skill → gh skill install oubakiou/mdxg-redline md-review (usage details)

If you've tried it with your agent workflow, I'd love to hear how the structured JSON feedback format worked for you — drop a comment below or open an issue on GitHub.