mkdn

the reading side of the agentic loop. code, diagrams, and math, rendered natively and updated live.

Install View on GitHub

Review, not write

not a code editor. a viewer built for comprehension — select anything and leave a comment your agent reads back.

Native, not Electron

pure SwiftUI. launches instantly, idles at nothing, feels like it belongs on your Mac.

Live, not stale

File watching at the kernel level. When an agent writes a file, mkdn re-renders it instantly. No reload button.

comments that live in the file

select text — a word, inline code, mid-sentence — and comment on it. the comment is stored in the .md file itself, so it survives in git, passes invisibly through other renderers, and re-finds its text when the prose around it moves.

mkdn in Solarized Dark with the comment rail open. An agent named claude replies to the comment 'where did 200 ms come from?' and the reply pops into the thread under the card the instant it is written from the CLI.

An agent replies from the CLI and the thread updates live in the open window — no reload, no refresh.

Two overlapping comments on one sentence: an outer highlight over 'a single logical edit often lands as three writes inside 40 ms' and an inner highlight over 'three writes inside 40 ms', with a small badge reading 2 where they meet, and each comment shown as a card in the rail. — Comments nest and overlap — a badge counts how many share a span.

A single comment highlighting the words 'resolved path' in a sentence, with its card anchored directly beside that line in the rail, asking 'does this cover hardlinks too, or only symlinks?'. — Every comment anchors beside the exact line it annotates.

A rail of cards

comments sit beside the text they annotate and follow it as you scroll. click a card to jump to its spot. replies thread underneath.

Survives outside edits

rewrite the prose in another editor, merge a branch — the comment re-anchors by what its text says, not where it sat.

Headless for agents

no window needed. an agent lists comments as JSON, replies into the thread, or blocks until you leave a new one.

mkdn comments list plan.md
mkdn comments reply plan.md k7 "fixed in 3a41c2" --author agent
mkdn comments wait plan.md

what agents produce, rendered natively

Mermaid diagrams

flowcharts, sequence diagrams, state machines, all inline and interactive.

Syntax highlighting

Tree-sitter highlighting across 17 languages. Code blocks with language labels, themed backgrounds, and click-to-copy.

LaTeX math

block and inline equations. renders like a textbook, not a code block.

Tables, lists, rich text

full CommonMark. tables size to their content, select like real text, and paste straight into a spreadsheet.

Solarized theming

dark and light modes that match your terminal. built for long sessions.

Directory browsing

point it at a folder. sidebar, file watching, the whole tree at a glance.

Fast on big documents

the first screen paints in about a third of a second. the rest fills in quietly behind it.

A marker track

headings and comments plotted along the right gutter. tap to jump, drag to scrub, or swap in a minimap.

VoiceOver-ready

custom rotors for headings, links, and comments. tables read with column context.

Get started

macOS 14.0 or later.

Homebrew

brew install jud/mkdn/mkdn

Build from source

git clone https://github.com/jud/mkdn.git && cd mkdn && swift run mkdn