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 in early preview. It supports macOS 14 Sonoma or newer on Apple Silicon Macs and requires Node.js 22.13.0 or newer for the launcher. Native Intel releases are deferred; see issue #80.
Ordinary review work stays in your macOS account. Markover has no telemetry, analytics, cloud sync, or automatic review upload. Data formats from unreleased prototype builds may change without migration support. 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. Advanced users can follow the tailnet-only Tailscale Serve example for a manually authorized remote client. 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 chat apps do not open custom-scheme links directly. Whether Markover switches to the incoming review immediately is controlled by Settings → Incoming reviews → When you open a review link; the default is to switch immediately.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 in the center pane and write Markdown feedback in the right pane's annotation view. 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. Agent handoffs and reopened reviews are fully saved 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; at the first or last sibling, continue at the parent's level |
| Left | Select the parent block |
| Right | Select the first child, then the next available sibling |
| Tab / Shift-Tab | Move among the left, center, and right 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.