the reading side of the agentic loop. agents produce markdown — plans, code, diagrams, docs — and mkdn renders all of it natively on macOS. SwiftUI + TextKit 2, not a web browser in disguise.

and now the writing-back side: select text, comment on it. comments live in the .md file itself, and agents read them with mkdn comments.

Homebrew:

brew install jud/mkdn/mkdn

Build from source (macOS 14+, Xcode 16+, Swift 6, Apple Silicon):

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

mkdn file.md
mkdn docs/ # directory mode with sidebar

Also supports Cmd+O and drag-and-drop.

mkdn comments list file.md # read comments + reply threads as JSON
mkdn comments reply file.md k7 "done" --author agent
mkdn comments wait file.md # block until new comments appear

Everything agents produce:

• CommonMark via swift-markdown — headings, lists, tables, blockquotes, images, inline formatting
• Fenced code blocks with tree-sitter syntax highlighting (Swift, Python, JavaScript, TypeScript, Rust, Go, Bash, JSON, HTML, CSS, C, C++, Ruby, Java, YAML, Kotlin, TOML)
• Source code files — open .swift, .py, .rs, or any text file directly. full syntax highlighting, line numbers, horizontal scrolling
• LaTeX math — inline $...$ and display $$...$$ via SwiftMath
• Mermaid diagrams in lightweight embedded WKWebViews (one per diagram, bundled mermaid.js, no network requests)

the comment rail in Solarized Dark: highlighted spans in a document, each with an anchored card, one holding a threaded reply from an agent

select text — a word, inline code, mid-sentence — and comment on it. the comment lives in a sidecar block at the end of the .md file, so it survives in git, passes invisibly through other renderers, and re-finds its text by what it says, not where it sits. edit the prose around a comment in another editor and it re-anchors; if its text is gone, it collects in a detached footer instead of vanishing.

• comment rail (Cmd+Shift+C) — cards beside the text they annotate, following the scroll; a header toggle springs them into a compact stack and back
• reply threads — replies nest under comments; agent replies via mkdn comments reply carry their author name
• paste-to-comment — paste onto a selection and the pasteboard text becomes a comment on it
• headless access — mkdn comments list | reply | wait for agents, no window needed

format reference: docs/features/markdown-comments/comment-format.md

• Solarized Dark / Light themes (auto-follows system, or pinned)
• Staggered entrance animations — content cascades in on load and file switch
• Find in page (Cmd+F, Cmd+G / Cmd+Shift+G to navigate)
• Document outline (Cmd+J) — collapsible heading tree with a breadcrumb trail
• Marker track — headings and comments plotted along the right gutter, draggable thumb; swaps for a minimap (Cmd+Shift+M)
• Real text selection in tables — drag across cells, double-click a word, triple-click a cell; Cmd+C pastes straight into a spreadsheet
• Big documents open fast — first screen paints in ~a third of a second, the rest fills in behind it
• VoiceOver-ready — custom rotors for headings, links, and comments; labeled table semantics
• Side-by-side editor with live preview
• Zoom (Cmd+/-, persists across sessions)
• File watching — kernel-level DispatchSource, breathing orb on change
• Chrome-less window — no title bar, no traffic lights
• Directory browsing with sidebar (Cmd+Shift+L to toggle)
• Print (Cmd+P)

Two-target SPM layout: mkdnLib (library) and mkdn (thin executable entry point). Feature-Based MVVM. Tests use @testable import mkdnLib — 844 tests across 89 suites.

mkdn/
 App/ Entry point, AppSettings, commands
 Features/
 Viewer/ Markdown preview (TextKit 2 rendering)
 Editor/ Side-by-side editing
 Sidebar/ Directory browsing
 Outline/ Document outline navigator + breadcrumbs
 Core/
 Markdown/ swift-markdown parsing + NSAttributedString, comments
 Mermaid/ WKWebView + mermaid.js diagram rendering
 Highlighting/ Tree-sitter syntax highlighting
 Math/ LaTeX math rendering
 FileWatcher/ Kernel-level file change detection
 DirectoryScanner/ Recursive Markdown file discovery
 DirectoryWatcher/ Directory-level change monitoring
 Git/ Git status for the sidebar
 Services/ Shared service layer
 CLI/ Argument parsing, mkdn comments
 Instrumentation/ Performance instrumentation
 TestHarness/ Visual testing infrastructure
 Platform/
 iOS/ iOS-specific view implementations
 UI/
 Components/ WelcomeView, BreathingOrb, ModeOverlay, WindowAccessor
 Theme/ Solarized color palettes, ThemeMode, DesignTokens
 Resources/ mermaid.min.js bundle
mkdnEntry/
 main.swift Executable entry point
mkdnTests/
 App/ App-level tests
 Unit/ Unit test suites
 Support/ Test helpers and fixtures

Plus 17 tree-sitter grammar packages (one per language, pinned for build reproducibility).

mkdnLib also compiles for iOS 17+. The Platform/iOS/ layer provides 8 view implementations (text blocks, code blocks, math, images, tables, Mermaid). The app itself is macOS-only.

MIT License. See LICENSE for details.