How to read the Markdown files your AI agent writes, on a Mac

AI coding agents write a lot of Markdown. Claude Code, Cursor and similar tools produce plans, specs, research notes and summaries, and they save them as .md files in your project. These files are where the agent tells you what it wants to do. Reading them carefully is the cheapest review step you have.

The problem is small but real: the files show up on disk, often several per session, and the default way to look at them is raw text in a terminal or an editor tab. This post goes through three ways to read them on a Mac, with the trade-offs of each.

Why it is worth reading them properly

A plan is easier to judge when it looks like a document. Headings show the structure. Tables line up. Code blocks stand apart from prose. A task list reads as a list.

In raw form, the same file is a wall of #, | and backticks. You can read it, but you skim more and catch less. With agent output, the things you miss are the things that cost you later: a wrong assumption in step 3, a file the agent plans to delete, a scope that grew.

Agents also rewrite these files while they work. A plan changes after your feedback. A status file gets a new line after each step. So it helps when the thing you read from updates on its own.

Option 1: the editor preview

If you work in an editor, its Markdown preview is the nearest tool. VS Code and Cursor have one built in. Open the file, open the preview, and you see the formatted document beside the source.

What is good:

• Nothing to install.
• You stay in the app where the agent runs.
• You can switch to the source and edit right away.

What is less good:

• The preview takes space from your code. On a laptop screen, a side-by-side preview is narrow.
• You open it file by file. With many agent files, that is a lot of tabs.
• Terminal agents such as Claude Code do not need an editor at all. Opening one only to read a plan is a detour.

Option 2: Quick Look in Finder

Quick Look shows a preview when you select a file in Finder and press Space. With a Markdown Quick Look extension installed, the preview is formatted. Press the arrow keys to step through the other files in the folder.

What is good:

• Very fast for a glance. No window to manage.
• Good for browsing a folder of plans or specs to find the right one.

What is less good:

• You have to find the file in Finder first. Agent files often sit in hidden or nested folders.
• A Quick Look panel is for looking, not for long reading. It closes when you move on.
• Without an extension, Quick Look does not format Markdown.

Option 3: a Markdown viewer

A viewer is a separate app that opens a .md file and shows it formatted. For agent output, three things matter:

• Read-only. You are reviewing, not writing. A viewer that cannot change the file cannot break what the agent wrote.
• Live reload. When the agent updates the file, the view updates too. You keep one window open next to the terminal.
• Navigation. Long specs need an outline and search.

The cost is one more app, and a step to get the file into it. You can set the viewer as the default app for .md files, so a double-click or open plan.md in the terminal does the right thing.

Making files open by themselves

The remaining friction is the step between “the agent wrote a file” and “the file is in front of me”. Some agents support hooks: small commands that run when something happens, for example after the agent writes a file. A hook can open new Markdown files in your viewer.

Markko has a setup script for this. It installs auto-open hooks, so Markdown your agent writes opens in Markko:

curl -fsSL https://markko.app/setup | bash

As with any script you pipe into a shell, it is fair to read it first. Open https://markko.app/setup in a browser or download it with curl and look at what it does before you run it.

A simple routine

Whatever tool you choose, a short routine helps:

1. Ask the agent to write its plan to a file before it changes code.
2. Read the plan formatted, top to bottom. Use the outline to check that nothing is missing.
3. Give feedback in the chat. Let the agent update the file.
4. Watch the file change, then approve.

Where Markko fits

Markko is a native, read-only Markdown viewer for macOS. The free version shows GitHub Flavored Markdown, reloads when the file changes, has an outline sidebar, find, window tabs and a Quick Look preview. It never changes the Markdown file.

Markko Pro is a one-time in-app purchase of €12.99. It adds Mermaid diagrams and KaTeX math, which agents use often in plans, plus comments stored in a sidecar file next to the Markdown file, and export to PDF and HTML.