human-review parks your agent while you edit, and HTML files save themselves before you press Send

The agent is held while you review, and how long depends on which harness you are in

The interaction is that a review session keeps your coding agent occupied until you send. The mechanism is described in two different terms for two different harnesses, and the difference is not cosmetic.

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, so if the turn has already ended you have to send a message for the feedback to be collected.

That means the same review session can be a smooth handoff on one harness and a manual poke on another, with nothing in the interface telling you which mode you are in. What is uniform is the release. Closing the tab or clicking End review releases the agent either way, so there is always an exit that does not depend on the agent cooperating.

Unsent feedback is not thrown away. Whatever you typed and did not send is kept, and the next time you open that same page you can restore it or discard it. So the tool's failure mode is paused work rather than lost work, which is the right way round for something that holds a process open.

HTML files write themselves to disk, Markdown and localhost pages wait for Send

This is the sharpest edge in the tool, and it runs the opposite way from what the interface suggests. For HTML files, direct edits and image resizes save automatically, so closing the tab does not undo them. The ways back are Discard on your next open, or Revert all during the review.

For Markdown files and for localhost pages, you click Send and your agent applies the changes to the source.

So the case where nothing happens on close is Markdown, and the case where your work is already on disk without a Send is HTML. If you are reviewing a generated landing page and decide halfway through that the direction is wrong, the file is already modified. The two recovery commands are named in the same paragraph, which tells you they are the ones that get used.

The localhost path behaves differently again in one more respect. Pasted images during a file review are saved beside the document, while pasted images during a localhost review are staged for the agent to place in the app source. Reviewing a page on disk can therefore create new files in your project directory as a side effect of a paste.

A comment you already sent can be reworded, and the agent reads the new wording

Comments are editable after they are written, including after they have been sent. The stated behaviour is that a reworded comment reaches the agent with the next Send.

Set that against the batch model. Everything you did since the last Send goes to the agent in one batch: edits, deletions, moves and comments together. So a comment you sent, watched the agent act on, and only then realised was imprecise can be corrected, and the correction arrives as part of a later batch rather than replacing what was already acted on.

The agent therefore acts on text you never approved in the form you approved it. In practice that is usually a benefit, because you spot the imprecision after seeing the result and the fix lands immediately. It does mean the record of what was asked and what was read are not the same artefact at every point in the session.

The same batch carries the structural edits. Removing an element does not require explaining the deletion in chat, deletes and moves come with an Undo, and a comment can be anchored to an exact phrase of text or attached to an image, a chart or a section by clicking the element.

`node --test --test-force-exit` is the test command for a tool that holds processes open

The whole test script is:

"test": "node --test --test-force-exit --test-timeout=60000"

`--test-force-exit` ends the test process once the tests report, rather than waiting for the event loop to drain. For a project whose entire job is to start a local review server and block a coding agent until a human clicks Send, that flag will hide exactly the class of problem the tool is most exposed to: a server, a socket or a poll timer left open. The 60-second timeout is the other half of the same arrangement, generous enough that a genuinely hung test still gets cleaned up.

The test environment is equally telling. There is one development dependency, `jsdom`, and one runtime dependency, `marked`. So the test suite drives the DOM in Node rather than in a real browser, and the review interface in `src/chrome-client.js` is hand-written with no framework and no bundler.

There is also no build step at all. The manifest's `bin` points at `src/cli.js`, the `start` script runs `node src/cli.js`, and `files` ships `src` directly. What npm delivers is the source tree, unmodified, which is the simplest possible supply chain and also means no compilation step can catch anything.

The keyboard layer is macOS, and the pitch is every agent on every platform

The editing shortcuts are written with the Command key. Bulleted and numbered lists come from typing `- ` or `1. ` at the start of a line, or from pressing ⌘⇧8 and ⌘⇧7. Links are added by selecting text and pressing ⌘K, and pressing ⌘K inside an existing link edits or removes it. Tab and Shift+Tab indent and outdent, and that pair is the exception because it is not Command-modified.

The installation section names ChatGPT, Claude Code, Codex and your favorite coding agent as targets, and the prerequisites are Node 20 or newer with nothing else platform-specific. The repository runs on any machine with Node.

The gap is that list creation and link editing, which are the two operations a reviewer does most while rewriting copy, have no documented keyboard path on Linux or Windows. The typing fallbacks survive, so the feature is reachable; the speed is not.

The mouse side is platform-neutral and does more of the work anyway: drag an image corner to resize it, drag an image to move it, hover a block and drag the handle on its left edge to move the whole block, and command-click links to move between pages without losing feedback.

Both install paths resolve whatever is current, under a short unscoped package name

There are two ways in and neither pins anything.

The first is an instruction you paste into ChatGPT, Claude Code, Codex or another coding agent:

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

The second is:

npx -y human-review setup --global

`npx -y` takes the current published version. The paste path names a repository with no ref in it, so the agent fetching it is reading whatever is on the default branch. For a tool whose whole job is to write to your files and hold your agent open, that is the one decision worth making deliberately rather than by reflex.

The registry name is `human-review`, unscoped and two ordinary words. On the public registry that is a short name in a crowded space, and it is the string a typo could walk into.

The CLI itself has four commands, `human-review`, `poll`, `status` and `setup`. Only `setup` appears in the README. `poll` is the one an agent uses to wait for your feedback, and its contract is taught to Claude Code and Codex through `src/SKILL.md` rather than in the README.

Three release notes in a row describe the interface, and none mention the agent protocol

The recent tags read as a UI changelog. v0.8.2 is tabs and toggles click through. v0.8.1 is count only what the agent doesn't have yet. v0.8.0 is diagrams, Back, and drops past the whole card.

All three are interface behaviours. None of them mentions the wait-and-release protocol, the difference between a background wait and a turn-bounded wait, or the HTML auto-save behaviour, which are the three things most likely to surprise someone adopting this.

The dates are also tight. v0.8.0 and v0.8.1 both landed on 2026-09-04, thirty-seven minutes apart, and v0.8.2 followed on 2026-09-17. The manifest is at 0.8.2, matching the latest tag, and the project is pre-1.0 with a semantic version that has not settled.

The repository root carries `design-ref/`, `spec-assets/`, `spec.html`, `assets/` and `test/`. None of them is in the `files` array, which ships `src`, `README.md` and `LICENSE`. So the design references and the spec document are development artefacts that never reach an installed copy, while the README points its demo video at a GitHub user-attachments URL rather than at the local `assets/` directory.

Editorial conclusion

Reach for human-review when the alternative is typing paragraph-by-paragraph instructions into a chat window and then re-reading the file to check the agent understood them. It earns its keep on long Markdown plans and on landing pages where the copy needs reshaping rather than fixing. Five things to know before a session. On HTML files, edits and image resizes hit disk the moment you make them, with Discard and Revert all as the only way back. The agent only stays parked as long as your harness allows, so Claude Code and Codex behave differently. A comment you already sent can be reworded and the new wording is what the agent reads next. The keyboard layer is macOS only. And both install paths, the npx command and the agent-directed paste, resolve whatever is current at the moment you run them.

Frequently asked questions

Official sources

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