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 command blocks until the user hits Send in the browser, then prints their batch and exits:

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

   The command exits only when the user clicks Send or closes the review. There is nothing to re-run, no interval to poll on, and no --timeout to add. It survives the local server restarting, and feedback is saved even if the poll dies, so nothing is ever lost. How you wait depends on your harness:

   • Claude Code: run it with run_in_background: true and end your turn. Claude Code wakes you with the output the moment the command exits.

   • Codex, Cursor, and everything else: run it in the foreground, inside your active turn, and stay on it until it prints feedback or closed. Do not detach it or start it as a background session: nothing wakes you when a detached command finishes. While the review is active:

     • If the user sends a message, answer it as commentary and immediately resume the foreground poll in the same turn. Do not send a final response until the poll returns feedback or closed — a final response ends the turn and kills the wait.
     • If your shell tool caps command duration, pass --timeout a little under the cap and run bounded polls back to back in the same active turn until one returns feedback or closed.

     Know the limit: this is reliable only while your turn stays active. A turn that has already ended is not woken when the user hits Send; the user has to message you, and you then run status and poll to pick the batch up. There is no integration that resumes an ended task when the poll exits.

   If it prints {"status":"closed"}, the review is over: the user ended it, closed the tab, or never had one open (reason says which). Stop and do not start another poll. unsent counts feedback they left behind; if it is not zero, tell the user in one line that it is kept and they can restore or discard it next time. {"status":"superseded"} means a newer poll of yours owns the wait — stop this one silently. {"status":"timeout"} only appears after 12 hours; run status and start the wait again if the review is still open.

4. Apply what comes back, then start the next background poll. --ack clears the batch you just handled:

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

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 with no poll running? 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.

What you get

One batch covers every page the user visited, grouped by file or localhost URL.

{
  "status": "feedback",
  "pages": [
    {
      "file": "/abs/path/to/page.html",
      "edits_saved": true,
      "comments": [
        { "id": "c_1", "kind": "selection", "quote": "the exact text they selected",
          "anchor": { "prefix": "...", "quote": "...", "suffix": "..." },
          "feedback": "what they want changed" }
      ],
      "edits": [
        { "label": "Problem body", "kind": "edited",
          "before": "the original wording",
          "after": "their exact new wording",
          "after_html": "their exact new wording with <strong>formatting</strong>" }
      ]
    }
  ],
  "overall_note": "feedback not tied to any one page"
}