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.

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:

Contributing

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