@wipcomputer/markdown-viewer

WIP Computer

Live .md Viewer

Live markdown viewer for AI pair-editing. When you collaborate, the updates render instantly. Works with any AI agent and web browser.

How It Works

• Tell your AI coding tool to install @wipcomputer/markdown-viewer globally
• Tell your AI to open the demo.md (or any .md) in md view
• AI will open the file in your default browser
• Every save re-renders the page instantly. No refresh needed.

Open multiple tabs to work on multiple documents at once.

Install

For AI Agents

Open your AI coding tool and say:

Install @wipcomputer/markdown-viewer globally,
start mdview, and add live viewer support to this project.

Your AI will install the package, start the server, and add the right instructions to your project so it knows to open the viewer whenever you edit markdown together. That's it.

npm

npm install -g @wipcomputer/markdown-viewer
mdview

That's it. Global install gives you the mdview command anywhere.

Options

mdview                         # Start server on port 3000
mdview --port 8080             # Use custom port
mdview --root /path/to/dir     # Restrict file access to this directory

From source

git clone https://github.com/wipcomputer/wip-markdown-viewer.git
cd wip-markdown-viewer
npm install
node server.js

Server starts at http://127.0.0.1:3000. Open any markdown file:

http://127.0.0.1:3000/view?path=/absolute/path/to/your/file.md

Supported Tools

This works with any AI agent that can run shell commands and edit files.

Tool	Instruction file	How to add support
Claude Code	CLAUDE.md	Add the snippet below to your project's CLAUDE.md
OpenAI Codex CLI	AGENTS.md	Add the snippet below to your project's AGENTS.md
Cursor	.cursorrules	Add the snippet below to .cursorrules
Windsurf	.windsurfrules	Add the snippet below to .windsurfrules
OpenClaw	SKILL.md	Install the live-viewer skill
Any other agent	Whatever config it reads	Add the snippet below

If your tool reads a project-level instruction file... it works. The snippet is the same for all of them.

Features

• Live reload: SSE-powered, works in all browsers including Safari
• Multi-file: each tab watches its own file independently
• GitHub Flavored Markdown: tables, task lists, strikethrough
• Syntax highlighting: 180+ languages via highlight.js
• Dark mode: light and dark themes
• Table of contents: auto-generated from headings
• Mermaid diagrams: flowcharts, sequence diagrams, and more
• Math equations: KaTeX rendering for LaTeX
• Drag and drop: drop any .md file onto the homepage to view it
• Zero external requests: all dependencies bundled locally, no CDN calls

For AI Agents

Everything below is for you, the AI agent. The human doesn't need to read this. When the user asks you to set up the live markdown viewer, follow these steps.

Step 1. Start the Server

If installed globally via npm (npm install -g @wipcomputer/markdown-viewer):

curl -s http://127.0.0.1:3000/ > /dev/null 2>&1 || mdview &

Or if cloned from source, resolve the full path and start the server:

curl -s http://127.0.0.1:3000/ > /dev/null 2>&1 || node {absolute path to wip-markdown-viewer}/server.js &

The server runs at http://127.0.0.1:3000 and stays running in the background. Note: the server doesn't survive reboots or long idle periods. The check above starts it only if it's not already running.

Step 2. Add the Snippet to Your Project

Add the following to whatever instruction file your tool uses (CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, or equivalent). The content is the same regardless of the file:

## Live Markdown Viewer

When editing a .md file, check the server is running and open it in the viewer:

  curl -s http://127.0.0.1:3000/ > /dev/null 2>&1 || node {path to server.js} &
  open "http://127.0.0.1:3000/view?path={absolute path to the file}"

Then make your edits. The user sees every change as you write. No refresh needed.
Do this every time you edit a markdown file.

Step 3. Every Time You Edit Markdown

• Run: open "http://127.0.0.1:3000/view?path={absolute path to the file}"
• Edit the file
• The user sees it update live in their browser

That's it. The server watches the file and pushes updates via SSE. You don't need to do anything else.

Notes

• macOS (Safari): The open command can drop query strings when Safari is already running. Prefer AppleScript:

  osascript -e 'tell application "Safari" to open location "http://127.0.0.1:3000/view?path={absolute path}"'
  

  Fallback: open "http://127.0.0.1:3000/view?path={absolute path}"
• Linux: Use xdg-open. Windows: Use start.
• Each file gets its own URL. Multiple files can be viewed in separate tabs.
• The server reads the file fresh on every change. No caching.
• If the server isn't running, start it. It doesn't need any arguments.
• Do NOT start the server with a file path argument. Always start bare (mdview or node server.js). Starting with a path locks the server to that directory.

Troubleshooting

Page shows the index instead of my file: The --root flag restricts which files can be viewed. If the server was started with --root /some/dir, files outside that directory will redirect to the homepage. Restart without --root to allow any path.

Safari shows a blank page or stalls: Safari aggressively caches SSE connections. Hard refresh with Cmd+Shift+R, or restart the server:

kill $(lsof -ti :3000); mdview &

open command drops the query string: macOS open can strip ?path=... when Safari is already running. Use AppleScript instead:

osascript -e 'tell application "Safari" to open location "http://127.0.0.1:3000/view?path=/your/file.md"'

Or navigate directly in the Safari URL bar.

Security

• Server binds to 127.0.0.1 only. It is not accessible from other machines.
• The /view?path= parameter reads files from your local filesystem. Use --root to restrict access to a specific directory tree:

mdview --root /path/to/your/project

When --root is set, the server will only serve files under that directory. Requests for files outside it return 404. Recommended when running in shared or multi-user environments.

License

MIT

Built by Parker Todd Brooks, with Claude Code and Lēsa (OpenClaw).