Guide
Getting started
Markover opens Markdown as a navigable document tree, stores feedback on individual blocks, and returns the complete review to an agent.
Before you try the early preview
Markover is an Early macOS preview. It supports macOS 14 Sonoma or newer on Apple Silicon Macs and requires Node.js 22.13.0 or newer for the bootstrap command. Native Intel releases are deferred to the Broad announcement roadmap. You do not need to clone the repository or install an npm package globally.
Ordinary review work stays in your macOS account. Markover has no telemetry, analytics, cloud sync, or automatic review upload. Unreleased prototype formats may change directly. Released review schemas are converted automatically with an original backup; unknown future versions remain untouched until a compatible Markover release opens them.
Before relying on Markover, read Markdown support and preview limitations and Privacy, storage, and recovery. Ask usage questions in GitHub Discussions.
Start a review with an agent
Tell your agent which Markdown file you want to review and why the review is useful. The agent opens that file in Markover and gives you a review ID, a best-effort Open in Markover link, and a standalone Terminal command. You do not need to clone the repository, install an npm package globally, or run the agent's launcher command yourself.
To start without an agent, choose File → Open Markdown…. Markover creates a managed local review from the selected snapshot, saves feedback and attachments separately, and restores that review after restart. The original Markdown file is never changed or deleted.
open 'markover://…' command the agent provides, paste it into Terminal, and press Return. Some thread-hosts do not dispatch custom-scheme links directly. Markover focuses and follows Settings → Incoming reviews → When you open a review link; links switch immediately by default.Agents and tool authors should follow the separate agent workflow for exact commands, review-ID handling, and feedback interpretation.
Open the ad-hoc app safely
The first launch is expected to show a macOS warning because Apple has not verified Markover's publisher. A valid ad-hoc seal proves that the app has not changed since it was sealed; it does not prove who produced it.
- Attempt the launch once so macOS records the blocked app.
- Open System Settings → Privacy & Security.
- Under Security, find the Markover message and choose Open Anyway.
- Confirm Open.
If you downloaded Markover.app manually, Control-click it in Finder, choose Open, and confirm Open. Override only an archive whose SHA-256 checksum came from the same GitHub Release. Do not recursively remove quarantine attributes.
See GitHub Releases for each release's checksums, provenance, trust status, and rollback information.
Review the document
Select a block in the document tree and write Markdown feedback in the annotation pane. Paste screenshots directly into the feedback field; attachments can be labeled and referenced as [!img-N].
The documents list keeps multiple reviews grouped by project. Use All annotations to read the active document's feedback as a single rendered list, or Annotated to filter the document tree to commented blocks.
Editing a source block creates a proposal. Markover preserves the original source and shows the proposed change as a word-level diff.
Durability and recovery
While Markover is responsive and local storage is healthy, managed review changes are durably saved within a two-second window by default. A normal quit first captures the latest editable reviews and finishes their saves. Exact agent handoffs and reopened reviews are committed before Markover reports success.
After an app crash or restart, Markover restores both reviews still being edited and reviews already inflight with an agent. You do not need to retrieve or drain agent reviews before restarting. Attachment bytes are flushed before saved review JSON can refer to them; a crash can leave harmless unreferenced attachment bytes, but not a durable broken reference.
See Privacy, storage, and recovery for the advanced autosave setting, quit choices after a save problem, and backup guidance.
Tell your agent the review is ready
Return to the agent conversation and say “Check Markover.” If you started the review with File → Open Markdown…, first open Review context in Markover, copy the Review ID, and include it in your message; the agent did not create that review and does not already know its ID. The agent retrieves one frozen handoff containing the source, document structure, annotations, attachments, source proposals, review context, and interpretation guidance.
If you need to add or correct feedback before the agent finishes, tell it to return the same review to editing; Markover keeps the review ID stable. After the agent acts on the complete handoff, the review becomes Revised and remains read-only. Start another feedback round as a new review. Reviews associated with a pull request become Done after an agent verifies that pull request merged.
Annotations remain free-form: they can request revisions, ask questions, discuss tradeoffs, and provide context. The handoff tells the agent to substantively address discussion and concerns, acknowledge questions explicitly, and treat exact source edits as context-dependent proposals.
Keyboard controls
| Key | Action |
|---|---|
| Up / Down | Move between sibling blocks; climb outward at a boundary |
| Left | Select the parent block |
| Right | Select the first child, then the next available sibling |
| Tab / Shift-Tab | Move between the document and annotation panes |
| Control-Tab / Control-Shift-Tab | Move between open documents |
| Enter | Edit the selected annotation from the all-annotations view |
Double-click a block, or use its disclosure control, to collapse or expand its children.