Agents write a lot of markdown. Plans, architecture decisions, handoff notes, CLAUDE.md. Most of the time I end up cat-ing these files or switching to VS Code just to glance at one. The file never needed editing. I just needed to read it.
So PonyMux added a markdown viewer to the Side Panel — read-only, scoped to .md files, rendered through the terminal itself. Not a file browser. Not a step toward becoming an editor. A place to glance at the documents that coordinate work between you and your agents, without leaving the terminal.
The distinction matters more than it sounds.
Why not a file browser?
The obvious feature request is a file tree. Several terminal products are heading that way — sidebar file explorers, inline previews, built-in editors. It's a natural direction. It's also a step toward becoming VS Code.
That's the tension. Every feature like that makes a terminal more capable and more complicated. At some point you're not improving the terminal anymore. You're building a second development environment inside it.
PonyMux has a principle called Stay small: a feature belongs here when it makes terminal sessions easier to find, understand, continue, or enjoy. Otherwise, it probably belongs somewhere else.
A file browser didn't pass that test. But there's a more interesting question underneath it: do you actually need to browse source code in your terminal mux?
Agents are increasingly the ones reading and writing code. They navigate files, they make changes, they run tests. What humans need to see more often are the documents that sit above the code — the plan the agent is following, the decision log it should respect, the README it just updated.
Markdown is the handshake format between you and your agent.
That's the file type worth supporting well. Not all files. This one.
What does the viewer actually do?
It's a read-only Markdown renderer that lives in the Side Panel, next to Sessions. Press ⌥⌘F or click the toolbar button. It renders .md files with styled headings, code blocks, tables, task lists, and inline images.
There are three ways to open a file:
-
Click a
file://link in terminal output — if it points to a.mdfile, PonyMux opens it in the viewer instead of Finder. -
pony open <path>from a script or agent — pushes the file into the panel programmatically. -
The file picker in the panel itself — standard open dialog, filtered to
.md.
Editing stays in your editor. This is for reading and confirming. The context menu has "Open with Default App" and "Reveal in Finder" for when you need to go deeper.
Agents are doing more of the writing. What you need more of is a place to read.
Can agents open files for you?
This is the part I'm most interested in. The viewer isn't just something you open manually — agents can push files into it.
When an agent finishes writing a plan, it can run pony open plan.md and the file appears in your Side Panel. A small toast shows who sent it — "Opened by Claude Code" or "Opened by Codex" — so you know why the panel popped up.
The same thing happens with file:// links. If an agent prints a path to a markdown file in its output and you click it, the viewer catches it. No Finder window. No editor launch. Just the rendered file, right there beside the terminal.
This flips the usual direction. Instead of you going to find the file, the file comes to you. The agent produces a document, and it shows up where you're already looking.
It's a small workflow change. But after using it for a few days, going back to cat DECISIONS.md feels like a step backwards.
How does it stay light?
The viewer borrows a few ideas from a browser without trying to become one.
Back and forward navigation works within the panel. Click a relative .md link inside a rendered file and it navigates in place — no new window, no stack of tabs. The chevrons in the header track where you've been.
You can pin up to ten files for quick access. Pinned files and recent files show up in the empty state when nothing is open. Each terminal maintains its own browsing history, so switching terminals swaps the context.
The history is deliberately ephemeral. Quit PonyMux and it clears. The viewer doesn't track what you've read across sessions or build a project model out of your file visits. It's browsing state, not persistent data.
One detail I like: the viewer renders through the terminal's own surface. Same font, same theme, same copy behavior. If you change your terminal theme, the viewer changes with it. It doesn't look like a different app was embedded beside your terminal — because it wasn't. File watching keeps it current: edit the file in your editor, the viewer refreshes automatically.
Just enough, not everything
There's a version of this feature that supports every file type, has syntax highlighting for source code, and lets you edit inline. That version would be genuinely useful. It would also mean PonyMux is now competing with the editor you already have.
I'd rather keep the boundary. Agents are getting better at reading and writing code. The part where humans still need to look carefully is the coordination layer — the plans, the decisions, the context documents that tell the agent what to do and tell you what it did.
A read-only markdown viewer is a small, specific answer to that. It doesn't try to replace your editor. It doesn't try to show you everything. It shows you the one format that matters most for the way agents and humans work together right now.
For the full details — keyboard shortcuts, pinning, and how pony open works from scripts — see the Files section in the docs.
Top comments (1)
"Markdown is the handshake format between you and your agent" is the sharpest justification I've read for keeping a viewer read-only. We produce the same pile of plans and decision logs, and the reading side is where the human actually spends the time — the writing belongs to the agent, the confirming belongs to us.
"Stay small" is also the harder rule to hold, because every feature like a file tree is individually defensible and collectively they turn a mux into a second IDE. How do you apply it in practice — is there an explicit review gate for "does this belong here", or is it a judgement call you make when a request lands? The difference shows up the moment other people start contributing.