Doc Review

Review HTML, Markdown, and localhost pages, edit when you choose, leave contextual comments, and send all feedback to your AI agent at once.

Read the original Human Review launch post

human-review.mp4

Problem

Giving AI feedback on files in chat is painful.

Sometimes you want to change one sentence yourself. Instead, you end up typing:

In the third paragraph, change X to Y. Cut the third card because it repeats the first one. Also rewrite the CTA.

Then the agent changes the file and you have to check whether it understood every instruction. This gets even harder when you’re reviewing a long plan, Markdown document, landing page, or multi-page website.

How to install /doc-review

The easiest way to install the skill is to paste this into ChatGPT, Claude Code, Codex, or your favorite coding agent:

Install the /doc-review skill globally from https://github.com/erdemtuna/doc-review

You can also install it with npx:

npx -y @erdemtuna/doc-review setup --global

This fork uses the doc-review command, /doc-review skill, and ~/.doc-review state directory. It does not install a human-review alias or migrate upstream state and skill files; remove those old files manually if you no longer need them.

How to use /doc-review

Open an HTML or Markdown file:

/doc-review (your file)

Review a page running on localhost:

/doc-review (localhost URL)

Doc Review opens in View (Editing off, comments enabled) so links, buttons, summaries, tabs, and application controls work normally. The centered mode selector switches to Edit (Direct editing on) when you want to change content directly. Commenting stays available in both modes.

Select text, or hover or focus an element, then use the nearby comment icon. Ctrl+Alt+M (Cmd+Option+M on macOS) opens a comment for the current selection. Press Enter to submit or Shift+Enter for a new line. On desktop the composer stays beside its target, or pins to the effective top or bottom scrolling edge when that target leaves view. Back to selection reveals the target without changing the draft. The full-width sheet is used only at the narrow responsive breakpoint.

Comments is the single toolbar entry point for the closed-by-default review drawer. Its feedback inventory scrolls independently while the overall note and Send to agent controls remain fixed. Submitting a comment creates its normal highlight and increments the count, but keeps the card closed until you activate its mark or choose Jump to. Focus returns to the exact element or selection you reviewed.

Aligned cards show Edit, Close, and More; drawer cards show Jump to, Edit, and More. Delete lives only in More and requires an inline confirmation. Quote hints preserve both the beginning and ending of long selections. Editing has explicit Save and Cancel controls: Enter saves, Shift+Enter adds a line, Escape cancels, and moving focus never autosaves. A draft follows its comment between aligned and drawer cards and keeps its caret through target movement.

For writable HTML files, Edit saves direct changes automatically. Markdown and localhost remain editable feedback-only surfaces: their rendered HTML is never written over the source, so click Send and let the agent apply those edits.

File and rendered Markdown reviews run with authored scripts and inline handlers blocked, an opaque iframe origin, and no popup or download permission. Their per-render message capability is rotated for every load and navigation. It is kept out of document URLs, HTML attributes, authored DOM, and global JavaScript state; the single-use artifact URL loads a same-origin bootstrap module under a nonce-based CSP. Relative assets, including a same-artifact <base>, resolve beside the reviewed file, while review navigation always stays relative to the source file. External bases are ignored.

Localhost reviews keep allow-same-origin, popup, and download compatibility so application behavior still works. Because localhost application scripts are trusted in that mode, the render capability provides correlation and stale message rejection rather than an authorization boundary. The authenticated parent still validates links and never exposes the raw-file save route to a localhost review.

Agent polling returns an immutable batch_id. After applying the batch, the agent acknowledges that exact receipt and keeps waiting:

npx -y @erdemtuna/doc-review poll path/to/file.html --ack b_0123456789abcdef --timeout 600

A stale or repeated batch ID is harmless: it never clears newer feedback. The complete acknowledgement command is included in each response's next_step.

What this skill lets you do

• Edit text directly and tweak basic formatting (e.g., bold, italic).
• Make bulleted and numbered lists — type - or 1. at the start of a line, or press ⌘⇧8 / ⌘⇧7. Tab and Shift+Tab indent and outdent.
• Add links — select text and press ⌘K. ⌘K inside an existing link edits or removes it.
• Resize images by dragging their corner, and move images by dragging them to a new spot.
• Rearrange the page — hover any block and drag the handle on its left edge to move the whole block somewhere else.
• Paste images from your clipboard — file reviews save them beside the document; localhost reviews stage them for the agent to place in the app source.
• Select a phrase and leave a comment from the contextual icon, or press Ctrl+Alt+M / Cmd+Option+M.
• Comment on an image, chart, control, or section from its hover or keyboard-focus affordance without taking over its normal click.
• Remove elements without explaining the deletion in chat.
• Command-click links to review multiple pages without losing your feedback.
• Send every edit and comment at once instead of writing a long chat message.

Doc Review works well for editing AI-generated plans, updating landing pages, reviewing localhost apps, and removing extra copy from a UX.

What’s inside

• cli.js contains the doc-review, poll, status, and setup commands.
• server.js runs the local review session.
• sdk.js handles editing, comments, highlights, and feedback.
• chrome-client.js contains the visual review interface.
• markdown.js renders Markdown files for review.
• SKILL.md teaches Claude Code, Codex, and other agents how to use Doc Review.

Everything runs on your computer. Doc Review doesn’t require an account, cloud service, database, or API key. Comment geometry remains local, transient presentation data and is never written to review state or sent to the agent. After the agent acknowledges the exact delivered batch_id, the comments carried by that batch disappear; newer comments and corrections remain.

Upstream project

Doc Review is an independent fork of Human Review, originally created by Peter Yang. The fork preserves the upstream MIT license and continues from the upstream v0.6.1 release.

License

MIT