Something quiet but profound has happened in the last year. Markdown files — READMEs, documentation, notes, technical specs — are increasingly written and edited not by humans typing in an editor, but by AI.
Tools like Claude Code, GitHub Copilot, Cursor, and Windsurf have changed the workflow. You do not open a .md file and type anymore. You tell the AI what you want:
“Add a troubleshooting section to the README.”
“Rewrite the API docs to include the new endpoints.”
“Update the changelog for this release.”
The AI modifies the file. You review the result. This is the new loop:
Human instructs → AI writes → Human reviews → Human instructs again
But here is the problem: where do you review?
The Gap in Today's Tools
Traditional markdown tools were designed for a different era. They fall into two categories, and neither handles the AI workflow well.
Markdown Editors (Typora, MacDown, iA Writer)
These are built around one assumption: you are the one typing. They give you a split pane or a live preview of your own keystrokes. When an external process modifies the file on disk, most editors either:
- Do not notice the change at all
- Show a disruptive “file changed on disk — reload?” dialog
- Lose your scroll position on reload
They were not designed for a file that changes every few seconds from an outside process.
Code Editors with Preview (VS Code, Sublime)
VS Code's built-in markdown preview is the most commonly used viewer today. It works — until an AI tool is rapidly rewriting sections of the file. The preview pane is tightly coupled to the editor's internal buffer. External file changes may not reflect immediately.
More importantly, when you are using Claude Code or a terminal-based AI tool, VS Code is not even in the picture. You are working in a terminal. You need a standalone viewer.
What an AI-Era Markdown Viewer Needs
When AI is the writer and you are the reviewer, the requirements change completely:
| Traditional Viewer | AI-Era Viewer |
|---|---|
| Reacts to keystrokes in the editor | Watches the file system for external changes |
| “Reload?” dialogs on file change | Silent, automatic refresh |
| Scroll resets on reload | Scroll position preserved across updates |
| Tightly coupled to an editor | Standalone — works with any tool |
| Editing features (bold, italic buttons) | Read-only — you are reviewing, not editing |
The ideal tool is like a live dashboard for your markdown files. You keep it open on one side of your screen. On the other side, you are instructing the AI in a terminal. Every time the AI saves the file, the viewer updates instantly — no flicker, no scroll jump, no dialog box.
How mdWatch Solves This
mdWatch is a native macOS app built specifically for this workflow.
It uses FSEvents — the same low-level file system API that powers Spotlight and Time Machine — to detect the instant a file changes on disk. When it does, the viewer re-renders the markdown without losing your scroll position.
Here is what that looks like in practice:
- Open a
.mdfile in mdWatch - In your terminal, run Claude Code (or any AI tool)
- Tell the AI to edit the file
- Watch the changes appear in mdWatch — in real-time
No reload button. No dialog. No lost scroll position. Just a live view of what the AI is writing.
Key Features
- Instant file-change detection — FSEvents-based, not polling. Changes appear within milliseconds.
- Scroll position preservation — Text-anchor-based scroll tracking means you stay where you were reading, even after a full re-render.
- GitHub-flavored rendering — The same CSS styling you see on GitHub. Tables, code blocks, task lists — all rendered correctly.
- Native Dark Mode — Follows your macOS system setting automatically.
- Read-only by design — No editing UI, no save conflicts, no accidental modifications. You are here to read.
- Lightweight — Native Swift app with zero external dependencies. Launches instantly, uses minimal memory.
The New Workflow
This is the workflow that mdWatch enables:
- Open your terminal and launch Claude Code, Copilot, or any AI coding assistant.
- Open the markdown file in mdWatch — keep it on the other half of your screen, or on a second monitor.
- Give the AI an instruction: “Update the README with the new API docs.”
- Watch it happen — as the AI writes, mdWatch renders each save in real-time.
- Give the next instruction — “Add a table comparing the old and new endpoints.” Watch it appear.
This is particularly powerful for:
- AI-assisted documentation — Watch your README evolve as you instruct the AI
- Code review with context — View the AI's changes to markdown specs and design docs in beautifully rendered format, not raw diffs
- Technical writing — Instruct the AI to draft, then review the rendered output as a reader would see it
- Learning and exploration — Ask the AI to write explanations and tutorials, and read them in a clean, formatted view
Why Not Just Read Raw Markdown?
You might think: “I can read the raw markdown in my terminal.” You can. But markdown is designed to be rendered. A table in raw markdown is hard to read. A nested list with code blocks is confusing. Images do not display. And when the document is 500 lines long, scrolling through raw text is painful.
mdWatch gives you the rendered output — the way the document is meant to be read — updating live as the AI writes it.
Try mdWatch
mdWatch is available on the Mac App Store. The next time you are working with Claude Code, Copilot, or any AI coding assistant, open your markdown files in mdWatch. You will wonder how you worked without it.