human-review

human-review

The user reviews your HTML, Markdown, or localhost page in a real browser: they fix small things by typing, select anything to comment on it, and send you the whole batch at once.

Markdown files open rendered. Their quotes and edits reference the rendered text, and the file itself is never touched — apply every change to the Markdown source, keeping its formatting syntax.

The loop

1. Write or update the HTML or Markdown file, or start the local page being reviewed.

2. Open it for the user:

   npx -y human-review path/to/file.html
   

   For a page served by a local development server, open the real route instead of recreating it as a separate HTML file:

   npx -y human-review http://localhost:3000/wiki
   

3. Wait for feedback. This blocks until they hit Send, or the timeout passes:

   npx -y human-review poll path/to/file.html --timeout 600
   

   Keep this command in the foreground. Do not end your turn while it is waiting. If your shell returns a process or session handle, keep waiting on that handle until the command exits. If it prints {"status":"timeout"}, no feedback has arrived yet — run the same poll command again to keep waiting. Feedback is saved even if a poll dies, so nothing is ever lost.

   If it prints {"status":"closed"}, the user ended the review from the browser — stop polling and do not run the poll command again. Unsent feedback is kept and ships the next time this target is reviewed.

4. Apply what comes back, then wait again. --ack clears the batch you just handled:

   npx -y human-review poll path/to/file.html --ack --timeout 600
   

Repeat 3–4 until the user says they are done.

Not sure whether feedback is already waiting — say, at the start of a new turn? This answers instantly without blocking:

npx -y human-review status path/to/file.html

It prints {"status": "feedback-waiting"} when a batch is ready for a poll, plus counts of unsent comments and edits still in the browser.