How to preview Markdown files from Claude Code and Codex

Claude Code just wrote the plan to PLAN.md, or Codex left a HANDOFF.md. You cat it and scroll through pound signs, asterisks, and pipes. The agents render Markdown in their own replies, but a file they write you read raw. A few ways to read it properly:

• In the terminal: glow PLAN.md renders headings, lists, tables, and code right there. Install it with brew install glow.
• In an app: open PLAN.md opens it in whatever app handles .md files on your Mac.
• Let the agent open it: add a line to AGENTS.md or CLAUDE.md telling it to run open on every Markdown file it writes.
• Click it: Claude Code prints file names as links. Cmd-click one to open the file.
• The catch: each of these sends you somewhere else to read, and back again to reply.

How do I read a Markdown file in the terminal?

Use a Markdown renderer. Glow is a common one:

brew install glow
glow PLAN.md

It prints the file with styled headings, bullet lists, tables, and highlighted code blocks, then returns to the prompt. For a long file, glow -p PLAN.md opens it in a pager you can scroll with the arrow keys and leave with q.

Glow reads from a pipe too, so cat NOTES.md | glow - works. It's the quickest way to read a plan without leaving the session's terminal, but it's a snapshot: when the agent edits the file again, run it again.

How do I open a Markdown file in an app?

macOS has a command for that:

open PLAN.md

It opens the file in the app your Mac uses for .md files, such as your editor or a Markdown app. To change which app that is, select any .md file in Finder, press Cmd-I, pick an app under Open with, and click Change All.

This works from anywhere, including from the agent itself, since it's an ordinary shell command.

Can the agent open the file for me?

Yes. Agents read your project instructions at the start of every session, so one line is enough. Add it to AGENTS.md, which Codex and Grok Build read, or to CLAUDE.md for Claude Code:

- After you write or update a Markdown plan or note, run `open <file>` so I can read it.

From then on, when the agent writes PLAN.md, it should finish by running open PLAN.md, and the file comes up in your Markdown app. If both agents work in the project, put the line in AGENTS.md and have CLAUDE.md import it with @AGENTS.md; see How to hand off a task from Claude Code to Codex.

Can I click the file name in Claude Code's output?

Yes. When Claude Code writes or edits a file, it prints the file name as a terminal link. In terminals that support links, such as Ghostty and iTerm2, hold Cmd and click the name, and the file opens in its default app.

That's handy when the agent mentions a file in passing. You don't have to copy the path or switch to Finder.

Can I read the file next to the agent's terminal?

Yes. PonyMux has a Files panel that renders Markdown beside the Terminal: headings, code blocks, tables, task lists, and images. Press Cmd-Option-F to show it.

PonyMux's Files panel rendering a Markdown file next to the Terminal, with back/forward navigation and a pin button.

A file gets there three ways:

• Cmd-click a link to a .md file in the terminal output, such as a file name Claude Code prints. It opens in the panel instead of another app.
• Run pony open PLAN.md in a PonyMux Terminal. The agent can run it too: put pony open <file> in the line above instead of open <file>, and a brief note shows which agent opened the file.
• Click a link inside a rendered file. Relative links to other .md files open in the panel, like a browser, with back and forward.

You can pin up to 10 files. The panel is for reading; to edit, open the file in your editor from its context menu. For more on the panel and the pony command, see Workspace and Navigation and pony CLI.

---

Originally published on ponymux.com, where the demos are interactive.