Previewing agent output in Finder

An agent has just finished a run and left a handful of Markdown files in the repo. A plan, a summary, some notes. You want to glance at them without opening anything, so you select one in Finder and press Space — and Quick Look shows you the raw source. Pound signs, asterisks, pipe tables that do not line up.

This is consistent, it is not a bug, and it has an exact cause that is worth understanding before you go looking for a fix.

Why macOS shows you the source

macOS does know what a Markdown file is. Ask the system about one and it will tell you the content type is net.daringfireball.markdown — a real, named type, not a fallback.

$ mdls -name kMDItemContentType -name kMDItemContentTypeTree plan.md
kMDItemContentType     = "net.daringfireball.markdown"
kMDItemContentTypeTree = (
    "public.item",
    "public.text",
    "public.data",
    "public.content",
    "net.daringfireball.markdown",
    "public.plain-text"
)

The second line is the whole story. Content types form a hierarchy, and net.daringfireball.markdown conforms to public.plain-text. Quick Look looks for a preview generator that handles the file's type, finds nothing registered for Markdown specifically, walks up the tree, and finds the built-in plain-text previewer — which does its job correctly by showing you the bytes.

The workaround worth not adopting

A pattern that shows up among people working with coding agents: since Quick Look renders HTML happily, tell the agent to write HTML instead of Markdown. Now Space works.

It does work, and it costs more than it looks. Markdown is the format your agent's instructions files use, that your README is written in, that renders on GitHub, that diffs cleanly in review, and that every other tool in the chain expects. HTML is none of those things. Changing the format your work is stored in to satisfy a preview limitation is a large tail wagging a small dog — especially when the limitation is a missing preview generator and nothing more.

Getting a rendered preview instead

Quick Look previews come from app extensions. You install an app that contains one, macOS registers the extension, and Space starts rendering. There is no standalone plugin format any more — the extension always ships inside an app.

Two routes, with real trade-offs:

• QLMarkdown — free, open source and maintained: version 1.5.2 shipped on 30 June 2026, and the Homebrew cask is neither deprecated nor disabled. It is highly configurable, it supports macOS 11 and later, and it is Quick Look only — its app is a settings window rather than somewhere to read. Installed outside the App Store, it needs the usual Gatekeeper step on first run.
• An app with a bundled extension — anything distributed through the App Store or notarized for direct download is signed, so it enables without quarantine workarounds and updates through the normal channel.

Worth knowing if you are looking at older advice: MacDown is gone. Its Homebrew cask was disabled on 1 September 2026 for failing Gatekeeper checks, stuck at version 0.7.2. Guides recommending it are out of date.

When the extension is installed and Space still shows text

This is common enough to be worth a checklist — the short version is below, and the full diagnostic walkthrough covers the rarer causes. In rough order of likelihood:

1. The app has never been launched. macOS registers an extension when its containing app runs for the first time. Open it once.
2. The app is not in Applications. Extensions in apps run from Downloads or a mounted disk image are frequently ignored. Move it to /Applications and open it again.
3. The extension is switched off. On recent macOS this lives in System Settings → General → Login Items & Extensions → Quick Look. Confirm the app is listed and enabled.
4. Something else claims the type. If you have more than one Markdown-capable extension enabled, they compete, and which one wins is not something you control directly. Turn the others off.
5. The cache is stale. qlmanage -r reloads generators and qlmanage -r cache clears cached previews. Log out and back in if that does not take.

One more thing to be aware of: the Space-bar Quick Look panel and the Finder preview pane are not guaranteed to behave the same way. People do hit cases where Space renders a document correctly while the sidebar pane shows only an icon and a list of metadata. If your preview looks broken, check which of the two surfaces you are actually looking at before you start reinstalling things.

What this is worth in an agent workflow

Quick Look is a good fit for agent output specifically because most of that output is glance-and-move-on. Did it write the plan you asked for? Is the summary describing the right change? You do not need a window, an editor tab, or a project — you need two seconds of looking at a rendered page.

nicemd includes a Quick Look extension, and it is part of the free tier along with reading — installing the app and opening it once is the whole setup. The same renderer handles GitHub Flavored Markdown, Mermaid diagrams, KaTeX math and syntax-highlighted code, all bundled offline, so a preview never reaches the network.

For files an agent is still actively writing, previews and open windows have a second failure mode worth knowing about — see why previews go stale when an agent edits the file, or the wider guide to reading agent-written Markdown.