Browse and annotate your markdown docs in the browser.
Three-panel layout. Wiki-links. Live reload. AI annotation via MCP.

---

Quick Start

Requires Node.js 22+ — install it here if you don't have it. No other setup needed.

npx browsemark docs/          # Your project docs
npx browsemark specs/         # Spec-driven development files
npx browsemark .              # Current directory

Opens http://localhost:8521 in your browser.

---

AI Annotation

Send feedback from your browser to your AI coding agent — no copy-paste.

1. Browse your docs (from Quick Start above)

2. Connect your AI tool — one-time setup, one command:

# Claude Code — no restart needed
claude mcp add browsemark -- npx agentation-mcp server --mcp-only --http-url http://localhost:4747

3. Click any element — headings, paragraphs, code blocks, list items — and add your comment. Your AI agent picks it up via MCP.

Verify it works: ask your AI agent "List my annotation sessions" — if it responds, you're connected.

...and should work with any tool that speaks MCP.

Setup guide for all supported tools →

---

Use Cases

Workflow	What you get
Spec-driven development	Browse the PRDs, design docs, and task files your AI agent works from
Docs-as-code review	Render and annotate your team's markdown documentation before merging
RFC and ADR browsing	Navigate RFCs and ADRs with wiki-link cross-references
Any markdown directory	Personal notes, blog drafts, README collections

---

Options

npx browsemark <directory> --host 0.0.0.0 --port 3000 --silent

Option	Description	Default
<directory>	Path to serve	. (current)
--host, -H	Bind address	localhost
--port, -p	Listen port	8521
--silent, -s	Hide server logs
--no-open	Skip automatic browser launch
--version, -V	Print version
--help, -h	Show usage

---

Documentation

Guide	Description
Annotation Workflow	MCP setup for Claude Code, Cursor, Codex CLI, and more
Markdown Features	Wiki-links, Mermaid, syntax highlighting, and rendering details
API Reference	REST and WebSocket endpoints
Troubleshooting	Common issues and fixes
FAQ	Frequently asked questions

Highlights

💬 AI Annotation Click any element, add a comment, and your AI coding agent picks it up via MCP. No copy-paste.	📝 Three-Panel Layout File tree + rendered markdown + document outline — side by side, like an IDE.
🔒 Fully Local Everything runs on your machine. No cloud, no accounts, no data ever leaves your system. Localhost only.	🔁 Live Reload Edit a file in your editor, see it update in the browser instantly via WebSocket. No manual refresh.
🔗 Wiki-Links [[links]], [[links|display text]], [[links#heading]] — Obsidian-compatible resolution across your entire directory.	📊 Mermaid Diagrams Flowcharts, sequence diagrams, ERDs, and more — rendered inline.
🎨 21 Themes Light, dark, and auto mode. Custom fonts and syntax highlighting. Switch with one click.	⚡ Zero Config No build step. No deployment. No account. Just run: npx browsemark docs/

---

Contributing

Contributions welcome — bugs, ideas, or code. See CONTRIBUTING.md to get started.