Review a Markdown document with Markover

Open one review

Give Markover a 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 — not an intermediate harness.
• Pass --thread-host-thread-id only for a distinct host-owned identifier.
• Run 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, minimum macOS version, 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 some chat apps, including T3 Code and the Codex app, do not currently open them from Markdown. The standalone command is the reliable handoff.

Use the identity your agent can actually observe

These routes are supported when their environment variable is present and nonblank. Keep the thread host and model provider as separate facts, use the local machine name, and omit any host-owned thread ID you cannot observe.

T3 Code with Codex

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover open ./DOCUMENT.md \
  --summary "Review these decisions before implementation." \
  --thread-id "$CODEX_THREAD_ID" \
  --thread-host-kind t3code \
  --thread-host-provider codex \
  --thread-host-machine "$(hostname)"

Claude Code with Claude

npx --yes \
  --package=https://github.com/lastobelus/markover/releases/latest/download/markover-cli.tgz \
  markover open ./DOCUMENT.md \
  --summary "Review these decisions before implementation." \
  --thread-id "$CLAUDE_CODE_SESSION_ID" \
  --thread-host-kind claude-code \
  --thread-host-provider claude \
  --thread-host-machine "$(hostname)"

When neither exact identifier is available, generate a fresh high-entropy --handoff-key for that one review instead of inventing thread metadata.

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.

Check and resolve pending reviews

At any point, an agent can ask Markover for every unresolved review opened by its exact current requesting thread. The result contains review links, document purpose, responsibility, age timestamps, and pull-request association without exposing draft feedback or changing review state.

markover pending --thread-id THREAD_ID --thread-host-kind t3code --thread-host-provider codex

Pending reviews are a soft gate: planning and implementation can continue, but the agent surfaces every result before merging or finishing the thread. Silence and merge do not imply acceptance.

markover resolve mko_8f3a2c --outcome reviewed-no-notes
markover resolve mko_8f3a2c --outcome accepted-unreviewed
markover unresolve mko_8f3a2c

If the review contains feedback, attachments, or source proposals, Markover first shows the preserved feedback summary. Completion then requires the explicit Abandon feedback button; cancellation leaves the review unresolved. Manual outcomes can return to Needs me until Done.

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. It preserves an explicit resolution; an Editing or With agent review is recorded as Merged unresolved rather than inferred as accepted. A pull request with no matching local reviews is a successful no-op.

Use an agent as the reviewer

In Settings → Agent Review, choose whether reviewer agents may add annotations only—the default—or may also propose source replacements. Markover freezes this global choice when an agent claims a review, so a later settings change does not alter work already in progress.

markover get-for-review mko_8f3a2c > review.json
# The reviewer updates feedback and permitted sourceEdit fields in review.json.
markover submit mko_8f3a2c --input review.json

The review must be pristine when claimed: no existing feedback, attachments, or source proposals. The returned artifact contains dedicated reviewer instructions under review.agentReviewer.agentGuidance, the effective permission under review.agentReviewer.mode, and reviewer thread provenance when available. The agent returns the complete artifact as one atomic batch; Markover accepts all permitted findings or none.

While the agent is reviewing, the document is read only in Markover and labeled Agent reviewing. After submission it is labeled Reviewed, remains immutable, and appears in history. Markover shows a completion notice with an Open action, including an explicit no-findings message when the reviewer returned an empty result.

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.