Review a Markdown document with Markover

Open one review

Run markover help before a pull-request-associated open, get, revise, or done. Its machine-readable pullRequestStatus contract is the source of truth for the live GitHub lookup, status mapping, flags, and lookup-failure behavior.

Give Markover one Markdown path and a short summary of why the document exists and what feedback would help:

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover open ./DOCUMENT.md \
  --summary "Review these decisions before implementation."

When reliable thread metadata is available, pass the best observable requesting-thread or session ID with --thread-id. Use --thread-host-kind for the user-facing product or lookup namespace where the user would look for the thread, and --thread-host-provider for the LLM provider or model family in use rather than an intermediate harness. Pass --thread-host-thread-id only for a distinct host-owned identifier. Try the local hostname command and pass its result as --thread-host-machine. Use recommended product values when they match observable facts, preserve truthful unknown values, and omit anything unavailable rather than guessing.

On first use, the launcher downloads the Apple Silicon app; verifies its checksum, bundle identity, version, architecture, Sonoma floor, ad-hoc signature, and code seal; then atomically caches it. A successful command exits promptly with one JSON value:

{"reviewId":"mko_8f3a2c","status":"editing","reviewUrl":"markover://review/mko_8f3a2c"}

Give the reviewer all three opening aids: a best-effort [Open in Markover](<reviewUrl>) link, the raw review ID, and this Terminal fallback alone on its own line:

open 'markover://review/mko_8f3a2c'

Custom-scheme links work through macOS, but thread-hosts including T3 Code and the Codex app may strip or decline them. The standalone command is the reliable handoff.

Stop and wait for the reviewer

After open succeeds and you have given the reviewer the link, raw review ID, and Terminal fallback, stop. Do not poll Markover or wait through a blocking process. The reviewer can work in Markover for as long as needed.

Retrieve the handoff once, only after the reviewer says “Check Markover” or otherwise clearly says the review is ready.

Retrieve one frozen handoff

Use the retained review ID:

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover get mko_8f3a2c

get freezes the latest review, marks it read-only in Markover, and returns one JSON object containing the exact source and checksum, document tree, annotations, attachments, source proposals, review context, and agent guidance. Repeating get is idempotent, but ordinary agent workflow retrieves once and acts on that result.

Validate the handoff before reading it

Require format: "markover-review" and version: 1 before interpreting any other field. Ignore unknown additive properties and keep them intact when writing the artifact. For any other header, leave the review untouched, follow the diagnostic to the official compatibility catalog, and recommend the listed Markover release. Never guess how an unknown version is shaped.

Reopen feedback only when requested

If the reviewer needs to add or correct feedback after handoff, return the same review to editing:

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover edit mko_8f3a2c

Retain the same review ID, stop again, and wait for another explicit request to retrieve it.

Record the completed handoff

After acting on every part of the frozen review, mark it Revised before reporting completion:

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover revise mko_8f3a2c

Revised reviews remain read-only. If another feedback round is useful, open the revised document as a new independent review.

Complete reviews after merge

After verifying a pull request merged, use its canonical URL and the verified merged observation:

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover done https://github.com/OWNER/REPOSITORY/pull/123 --pr-status merged

Markover moves every matching local review to the terminal Done state. A pull request with no matching local reviews is a successful no-op.

Interpret feedback by intent

Annotations are free-form. One annotation can request a revision, ask a question, discuss a tradeoff, and provide context. Every handoff includes a fixed contract under review.agentGuidance.fixedContract: respond to each part by its apparent intent, substantively address discussion and concerns, explicitly acknowledge every question, and treat exact source edits as context-dependent proposals.

The handoff also carries the review's snapshotted review.agentGuidance.interpretationPolicy. Follow both fields before acting. Markover carries this guidance; it does not classify annotations into rigid types or apply changes itself.

Default policy

Use your judgment to respond to the review and make useful revisions. Ask for clarification when needed.

A question may reveal an obvious useful revision without requiring another round trip, but the response must still acknowledge the question. For example:

Removed X—you were right that it had no place there.

Possible stricter policies

A reviewer may replace the default interpretation policy in Markover settings before opening the review. These examples are starting points, not required formats.

Ask before uncertain changes:

Apply clear revision requests. Answer every question directly. Before making a change whose intent or effect is materially uncertain, ask for clarification.

Use an explicit completion summary:

Handle feedback in document order. In your final response, summarize revisions made, answer every question, and list anything left unresolved.