Human Review: Edit AI-Generated HTML and Markdown in the Browser, Then Send One Batch to Your Agent

The chat-message problem Human Review was built around

The README opens with a scenario most people who work with coding agents will recognise. You want one sentence changed. Instead you write something like "In the third paragraph, change X to Y. Cut the third card because it repeats the first one. Also rewrite the CTA." The agent edits the file, and now you are reading a diff to check whether it understood every clause. The failure mode is not that agents cannot edit files. It is that prose instructions about layout are a lossy channel, and the longer the document, the more clauses get dropped or misread.

Human Review's answer is to move the instruction out of chat and into the document itself. You open the file in a browser, make the edits you would have described, and leave comments anchored to the exact text you are talking about. Then you click Send once. The README's framing is that the agent receives all your feedback in one batch, updates the source, and refreshes the page for another review round.

The audience is narrow and specific: people who generate plans, Markdown documents, landing pages or multi-page sites with an agent and then need to correct them. The README names the author's own uses, editing AI-generated plans, updating landing pages, reviewing localhost apps, and removing the extra copy AI likes to add to UX. If you never review agent output as a rendered document, this tool has nothing to do.

What actually runs: a CLI, a local server, and a browser client

The repository layout is small enough to read in one sitting. The README's "What's inside" list names five source files plus the skill definition. cli.js holds the human-review, poll, status and setup commands. server.js runs the local review session. sdk.js handles editing, comments, highlights and feedback. chrome-client.js is the visual review interface. markdown.js renders Markdown files for review. SKILL.md is what teaches Claude Code, Codex and other agents how to drive the tool.

The data flow implied by those files is straightforward. The CLI starts a local server, which serves the document into a browser client. Your edits and comments accumulate in that session. When you click Send, the agent picks up the batch through the poll path and applies it to the source file. The README states plainly that everything runs on your computer, and that Human Review requires no account, cloud service, database or API key. That is a real architectural commitment, not a marketing line: there is no server-side component to trust because there is no server-side component.

The dependency list backs this up. package.json declares exactly one runtime dependency, marked, for Markdown rendering, and jsdom as a dev dependency for tests. The engines field requires Node >=20. A tool whose entire runtime surface is a local server and a browser page is easy to audit, which matters when the thing it edits is your working directory.

Installing the /human-review skill and running your first review

The README gives two install paths. The easiest is to paste an instruction into your agent, which lets the agent fetch and install the skill itself. The README's example text is:

Install the /human-review skill globally from https://github.com/petergyang/human-review

The alternative is the npx route, which installs the skill globally without going through an agent:

npx -y human-review setup --global

The package exposes a human-review binary pointing at src/cli.js, and setup is one of the four commands the README lists alongside poll, status and human-review. Node >=20 is required by the engines field, so check that first if the command fails immediately.

Once installed, you invoke it as a skill inside your agent rather than as a bare shell command. The README gives two forms. To review a file:

/human-review (your file)

To review a page already running on localhost:

/human-review (localhost URL)

The file opens in your browser. From there the README describes direct text edits, basic formatting such as bold and italic, bulleted and numbered lists via `- ` or `1. ` at the start of a line (or the keyboard shortcuts the README lists), links via selecting text and pressing the link shortcut, image resizing by dragging a corner, image moving by dragging, and block rearrangement by hovering a block and dragging the handle on its left edge. Selecting a phrase and commenting anchors the comment to that exact text; clicking an element comments on an image, chart or section. When you click Send, the agent receives the batch.

HTML saves automatically; Markdown and localhost pages do not

This is the part of the README most likely to surprise someone, and it is worth reading twice. For HTML files, direct edits and resizes save automatically. Closing the tab does not undo them. If you want them gone, you use Discard on your next open, or Revert all during the review, and the file goes back.

For Markdown and localhost pages, the behaviour is different: you click Send so your agent can apply the changes to the source. The README is explicit about this split, and the split has consequences. An HTML review session is writing to your file as you work, which means an accidental drag or a stray keystroke is already on disk before you have decided anything. The undo affordances exist, and deletes and moves come with an Undo, but the safety model is "revert after" rather than "confirm before". If you are reviewing an HTML file that is not under version control, that is a real risk.

Markdown takes the opposite approach. Nothing reaches the source until the agent applies it, which is safer but adds a round trip and depends on the agent actually doing the work. The README notes the same for localhost pages. So the two file types do not share a mental model: one is a live editor with an undo history, the other is a staging area. Plan your review habits accordingly.

The agent handshake: background waiting versus turn-bound pickup

Human Review only works if something is listening on the other end, and the README describes different behaviour per harness. In Claude Code, the agent waits in the background and picks up your feedback the moment you hit Send. In Codex and other agents, it waits during its turn; if the turn already ended, you send a message and it picks the feedback up.

That distinction is not cosmetic. In the background-waiting model, the loop is tight: review, send, the agent edits, the page refreshes, review again. In the turn-bound model, the agent is only receptive inside a window, so a long review session can outlive the agent's attention and require a nudge. The README also notes that closing the tab or clicking End review releases the agent either way, which is the escape hatch when you are done.

There is a recovery path for unfinished work. Feedback you never sent is kept, and the next time you open that page you can restore or discard it. That covers the case where you close the browser mid-review, but it does not cover the case where you sent feedback and the agent failed to apply it. The README does not document rollback for a batch that was sent and misapplied, so if that matters to you, keep the file in git and treat the commit as your undo.

Where Human Review is the wrong tool

The supported surface is HTML, Markdown, and pages running on localhost. That is it. If your review target is a PDF, a Figma file, a spreadsheet, a Word document, or a rendered email template, the README offers nothing, and no amount of browser-based editing will change that. The chrome-client.js interface is built around a document in a page, so the constraint is structural rather than a missing feature.

The localhost path deserves its own caveat. Reviewing a running app means the visual state you are commenting on is produced by your dev server, and the README says pasted images in localhost reviews are staged for the agent to place in the app source rather than saved beside a document. That is a different workflow from file review, and it puts more responsibility on the agent to interpret where an image belongs.

There is also a coordination cost the README does not dwell on. The tool assumes exactly one human reviewing and one agent waiting. Command-clicking links lets you review multiple pages without losing feedback, but there is no described mechanism for two people reviewing the same page, or for resolving conflicting comments. For a solo developer iterating with an agent on a landing page, that is fine. For a team doing editorial review of a shared document, it is not the tool the README describes.

Compared with just editing the file and committing

The obvious alternative is not another AI review product. It is opening the file in your editor, making the changes yourself, and telling the agent what you changed, or simply committing and asking the agent to read the diff. That approach has real advantages: your editor has years of keybindings and plugins, git gives you exact rollback, and nothing new is watching your working directory.

What it does not give you is the anchoring. A comment attached to a specific phrase, or a click on the element you want removed, carries information that a diff plus a chat message does not. The README's core claim is that you stop writing the paragraph about the third card and instead delete the third card and leave a note on it. Whether that is worth a new local server depends on how often your agent misreads spatial instructions. If your corrections are usually "rename this variable", your editor wins. If they are usually "this section is redundant and the CTA is buried", the anchoring is the whole point.

The second alternative is reviewing inside the agent's own interface, which is where most people start. Human Review's premise is that the chat box is the wrong place for layout feedback, and the README's opening example is a direct argument for that position. It is a fair argument, but it is an argument about workflow, not about capability: the agent could already edit the file. What changes is the precision of what you told it to do.

Licence, maintenance and what an upgrade costs you

The project is MIT licensed, both in the LICENSE file at the repository root and in the license field of package.json. MIT is permissive: you can use it, modify it and redistribute it, including commercially, provided the copyright notice and permission notice travel with it. That is the shape of the licence, not legal advice about your situation; if you are vendoring the source into a product, read the LICENSE file itself rather than this summary.

The practical implication of MIT here is that the skill is a small set of files you can read. If the author stops working on it, you can fork src/ and keep going. The repository is not archived, and the last push was on 2026-09-04, the same day as the v0.8.1 release. The release notes for that version are titled "count only what the agent doesn't have yet", and v0.8.0 is titled "diagrams, Back, and drops past the whole card", with v0.7.2 titled "see where it lands, undo when it doesn't". Those titles suggest the project is still finding the edges of the interaction model, particularly around undo and drag placement.

Upgrade cost is low on the surface: the package has one runtime dependency, marked, and a Node >=20 engine requirement. The real upgrade cost is behavioural. Because HTML edits save automatically and the undo affordances have been changing across patch releases, a version bump can change what "Revert all" or a drag does. Keep reviewed HTML files in version control so a version bump cannot cost you content.

Editorial conclusion

Adopt Human Review if you already run Claude Code, Codex or a similar agent and keep rewriting chat instructions about the third paragraph and the second card. Skip it if your review target is a PDF, a design file, or anything that is not HTML, Markdown or a localhost page, and skip it if you cannot accept an HTML file being written to disk before you confirm anything. Before trusting it on real work, verify three things: that your Node version satisfies the >=20 engine field in package.json, that your agent behaves as the README describes during its turn (Claude Code waits in the background, Codex and others pick feedback up during the turn), and that the automatic HTML save behaves the way you expect by opening a throwaway file, making one edit, closing the tab, and reopening it.

Frequently asked questions

Official sources

1. License: MIT
2. petergyang/human-review on GitHub
3. Project website
4. README
5. Releases