A single Claude Code session can leave a pile of Markdown behind it: an implementation plan, a progress file, research reports, a session summary. Somebody has to read all that, and reading it as raw markup in a terminal is miserable — every table is a wall of pipes, every checklist is brackets. Here's the setup I use for reading AI output on a Mac.
Step 1: Triage with Quick Look
Most of what an agent writes needs a ten-second skim, not a reading session. Select the file in Finder, press Space, skim, move on. Out of the box macOS shows Markdown as plain text, so you'll need an extension that renders it: QLMarkdown does it free (open source, built on cmark-gfm), or Peekdown (my app) does it as part of a $3.99 viewer.
If the file's still sitting in your terminal scrollback, glow report.md renders it right there, free (brew install glow). I covered every reading option in the preview guide; the rest of this article is specific to AI output.
Step 2: Watch the file, not the terminal
Agents revise their documents while they work: a plan gets written, revised, appended to. The terminal shows you diffs and chatter, not the current state of the file.
Open the plan in Peekdown and set Settings > Behavior > External change handling to Auto-reload. Now the preview updates every time the agent saves. A green arrow flicks in the toolbar so you know it happened. And if you have unsaved edits of your own when the file changes underneath you, Peekdown shows a conflict dialog instead of silently clobbering either side.
Two window tricks help here. ⌘⇧L and ⌘⇧R snap windows to the left or right half of the screen. Agent on one side, document on the other. And pin-on-top (the pin icon in the toolbar, or the Window menu) keeps the document floating above whatever else you're doing. No more running cat on the same file over and over to see whether the agent has touched it yet.
Step 3: Mark it up and send it back
Reading AI output is half the job; the other half is telling the AI what to change. That's what Peekdown's annotations are for. Select rendered text and a floating toolbar appears with five marks:
- Strike (S) — delete this
- Lock (L) — don't touch this
- Comment (C) — change this, and here's how
- Note (⌘⇧N) — document-level instructions, like "add a conclusion section"
- Block Note (⌘⇧B) — directions for a whole paragraph, list, or code block
When you're done, ⌘⌥⇧C copies everything as a structured prompt — a JSON array where each annotation carries before-and-after context, so the AI can find the exact text. Paste it into Claude Code, Cursor, ChatGPT, whichever you use; in a terminal, pbpaste | claude pipes it straight in. Peekdown then clears the annotations so the AI's edits land on a clean document, keeps a snapshot in case you want them back (⌘⌥⇧Z), and can write the whole set to a .json file next to the document (⌘⌥⇧E).
And since the file is being watched, the document in front of you updates on its own when the agent applies your corrections.
The config files, too
You open CLAUDE.md, llms.txt, and .cursorrules constantly to check what your tools are being told. They're really prose, and Peekdown opens and renders all three, so a CLAUDE.md reads like the document it is.
The whole setup
A Quick Look extension for triage: QLMarkdown free, or Peekdown's. glow if you're terminal-native. And for the full loop, Peekdown as the default app: auto-reload on, the plan pinned next to the agent, annotations for corrections. Peekdown is $3.99 one-time and needs macOS 15.0 or later; the triage half of this costs nothing at all. If you're still choosing a viewer, the roundup compares seven.