{"slug": "a-markdown-viewer-not-a-file-browser", "title": "A markdown viewer, not a file browser", "summary": "PonyMux added a read-only Markdown viewer to its Side Panel, letting developers render .md files directly in the terminal via a keyboard shortcut, file:// links, or the `pony open <path>` command. The feature is scoped to Markdown only and deliberately excludes a file browser or editor, following the project's \"Stay small\" principle. Agents such as Claude Code and Codex can push plan and decision documents into the panel, which shows a toast identifying the sender.", "body_md": "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.\n\nSo 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.\n\nThe distinction matters more than it sounds.\n\nThe 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.\n\nThat'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.\n\nPonyMux has a principle called [Stay small](https://ponymux.com/docs/philosophy#stay-small): a feature belongs here when it makes terminal sessions easier to find, understand, continue, or enjoy. Otherwise, it probably belongs somewhere else.\n\nA 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?\n\nAgents 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.\n\n**Markdown is the handshake format between you and your agent.**\n\nThat's the file type worth supporting well. Not all files. This one.\n\nIt'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.\n\nThere are three ways to open a file:\n\n`file://` link`.md` file, PonyMux opens it in the viewer instead of Finder.`pony open <path>`\nEditing 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.\n\n**Agents are doing more of the writing. What you need more of is a place to read.**\n\nThis is the part I'm most interested in. The viewer isn't just something you open manually — agents can push files into it.\n\nWhen 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.\n\nThe 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.\n\nThis 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.\n\nIt's a small workflow change. But after using it for a few days, going back to `cat DECISIONS.md` feels like a step backwards.\n\nThe viewer borrows a few ideas from a browser without trying to become one.\n\nBack 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.\n\nYou 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.\n\nThe 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.\n\nOne 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.\n\nThere'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.\n\nI'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.\n\nA 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.\n\nFor the full details — keyboard shortcuts, pinning, and how `pony open` works from scripts — see the [Files section in the docs](https://ponymux.com/docs/workspace-navigation#files).", "url": "https://wpnews.pro/news/a-markdown-viewer-not-a-file-browser", "canonical_source": "https://dev.to/heylittlepan/a-markdown-viewer-not-a-file-browser-3o7n", "published_at": "2026-09-12 15:42:02+00:00", "updated_at": "2026-09-12 16:15:16.695930+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["PonyMux", "Claude Code", "Codex", "VS Code"], "alternates": {"html": "https://wpnews.pro/news/a-markdown-viewer-not-a-file-browser", "markdown": "https://wpnews.pro/news/a-markdown-viewer-not-a-file-browser.md", "text": "https://wpnews.pro/news/a-markdown-viewer-not-a-file-browser.txt", "jsonld": "https://wpnews.pro/news/a-markdown-viewer-not-a-file-browser.jsonld"}}