Duodoc: a collab layer for AI-generated HTML docs

I’ve been building a side project called Duodoc. It’s a hosting and collaboration layer for AI-generated HTML documents. The repo is here.

This post is the longer version of why it exists.

The problem

Agents have started speaking HTML, not Markdown. Ask Claude for a design doc, a spec, a post-mortem, an exploration of six layout options, and increasingly what comes back is a self-contained HTML artifact with diagrams, mockups, collapsibles, and the occasional live demo. The artifact is richer than Markdown and, frankly, more carefully read than yet another 100-line MD spec.

The trouble is that HTML doesn’t travel.

1. You can’t review it. HTML diffs are noisy. PR tooling assumes Markdown.
2. You can’t share it. Browsers don’t open .html from email gracefully. The usual workaround is “upload to S3 and DM the link,” which nobody enjoys.
3. Reviewers can’t talk to it. No selection-anchored comments, no resolve queue, no version history.

I noticed I was generating HTML artifacts with Claude constantly and then doing something janky to share them. So I built the layer that I wished existed.

What Duodoc does

A short list of the parts that matter.

A sandboxed HTML viewer. Arbitrary AI-generated HTML rendered safely in a sandboxed iframe. No allow-same-origin. You don’t have to trust the model that wrote it.

Confluence-style inline comments. Comment cards live next to the anchored text, not in a separate panel. Anchors use a {before, text, after} fingerprint so they follow the text across versions when they can, and surface as “anchor not found” when the text has mutated past recognition. Replies thread inside the card. Resolved cards dim in place.

Versioning with a real diff view. Every push is a new version. Diff any two versions side-by-side or inline, with word-level highlights inside changed lines and collapsible blocks of unchanged context. Way more readable than raw HTML diffs.

A Markdown review view. Three-pass extractor (normalize, convert, polish) tuned against a fixture set of real Claude artifacts. Strips style and script noise, preserves collapsibles, real GFM tables, language-hinted code fences, callout blockquotes, math markers, and Mermaid fences for diagrams. So the doc can land in a PR or Notion when it’s ready.

AI-address-comments with a preview gate. One click on any open comment. Claude reads the doc, the comment, the anchor, and a self-captured screenshot of the rendered region, then returns a proposed revision. You preview it in a sandboxed iframe modal, accept to create v2 with auto-resolve, or discard. BYOK Anthropic key, stored only in your browser.

A CLI for the Claude Code loop. This is where it gets interesting. Once installed, any Claude Code session can push artifacts up and pull comments back down.

duodoc push my-doc.html       # creates a doc, prints URL
duodoc pull                   # writes .duodoc/comments.md

After pull, you tell Claude:

Address the open comments in .duodoc/comments.md by editing my-doc.html, then run duodoc push my-doc.html.

Claude reads the sidecar with author, anchor excerpt, and comment body. Edits the HTML in place. Ships v2. Loop until everyone’s happy.

For a one-shot terminal loop, duodoc address --all does the same thing without a Claude Code session in the picture.

The loop, as I actually run it

Claude generates doc.html  →  duodoc push  →  share URL
                                                 ↓
                                       reviewers anchor comments
                                                 ↓
                              duodoc pull  →  Claude addresses comments
                                                 ↓
                              duodoc push v2  →  back to reviewers
                                                 ↓
                                       export .md  →  lands in PR / Notion

Every step is mechanical. The only judgment call left is “is the doc ready yet?”

What it’s good for

A few shapes that have already paid off.

• Tech design docs with diagrams. Generate as HTML, share for review, anchor comments to specific paragraphs, export to Markdown when merged.
• PR write-ups Claude generated for you. Push to Duodoc, paste link in the PR description, reviewers comment without leaving the browser.
• Visual design exploration. Six layout options as a single HTML grid. Stakeholders comment on the one they prefer. Diff between iterations.
• Incident post-mortems. Rich HTML with timeline, charts, log excerpts. Comments capture follow-ups. Exported Markdown goes into the post-mortem repo.
• Specs for a future Claude session. Push spec.html. Reviewer marks ambiguities. Next session does duodoc pull and Claude addresses each one.

Try it

It’s live at duodoc.app. Paste any HTML, get a shareable URL, leave a comment, see how the loop feels. The CLI lives in @duodoc/cli.

I’m using it daily for my own work. If it lands for you, or if it doesn’t, I’d love to hear which part broke the spell.