On this page · 7 sections
Claude Code is one of the most useful developer tools to come out of the AI wave. You give it a task, it thinks, it builds. But between the thinking and the building, something interesting happens: it writes a plan.
These plans are real markdown files sitting on your disk. And almost nobody reads them properly. If you want to read Claude Code plans the way they were meant to be read — with proper headings, code blocks, and syntax highlighting — you need a real markdown viewer, not a text editor.
What are Claude Code plans?
When you give Claude Code a non-trivial task — refactoring a module, building a feature, debugging a hairy issue — it often creates a planning document before writing any code. These plans land in a hidden directory:
~/.claude/plans/Each file is a standard .md document. Inside, you’ll find structured markdown: headings for phases, numbered lists of implementation steps, code blocks with file paths, architecture decisions with rationale, and sometimes a breakdown of risks or open questions.
A typical plan might look like this on disk:
~/.claude/plans/2026-04-15-refactor-auth-module.mdAnd inside, it’s proper markdown — headings, nested lists, fenced code blocks, the works. These aren’t throwaway notes. They’re often the clearest explanation of what Claude is about to do and why. If you’re reviewing the code it produces, reading the plan first makes the diff make sense.
The problem: raw markdown is hard to read
Here’s what happens when you try to read a plan.
Double-click it on macOS. TextEdit opens. The path ~/.claude/plans resolves under your home directory, but TextEdit just shows you pound signs, asterisks, backtick fences, and no formatting whatsoever. A 200-line plan turns into a wall of raw syntax that your eyes bounce off of.
Double-click it on Windows. Notepad opens. The Windows path is %USERPROFILE%\.claude\plans (or C:\Users\<you>\.claude\plans). Same story, worse font.
cat it in the terminal. You get the raw text scrolling past. Readable if the plan is short, painful if it’s not. No syntax highlighting on the code blocks, no visual hierarchy between an h2 and a list item.
Open it in VS Code. This works — Cmd+Shift+V gives you rendered markdown with a preview pane. But now you’ve launched a full IDE to read a document. VS Code loads your workspace, your extensions, your file tree. It takes a few seconds, and it’s the wrong tool. You wanted to read, not edit.
The format is markdown. The content is valuable. The reading experience is terrible.
The fix: pin your plans folder in MDHero
MDHero is a native markdown viewer with a built-in lightweight editor. Its job is rendering .md files with proper formatting — headings, code blocks with syntax highlighting, lists, the lot — and letting you tweak them in place when you need to (Cmd+E to edit, Cmd+S to save). It opens in under a second and weighs about 8MB. No Electron, no browser engine, no workspace.
Here’s how to set it up for Claude Code plans:
Step 1: Open MDHero and pin the plans folder.
Use the pin folder feature to add ~/.claude/plans to your sidebar. This is a one-time setup. After this, every plan Claude Code writes shows up in your sidebar automatically.
Pin folder shortcut
In MDHero, hit Cmd+O (Mac) or Ctrl+O (Windows) to open the folder picker, navigate to your home directory, show hidden files, and select .claude/plans. Then right-click the folder in the sidebar and choose Pin. It stays there across restarts.
Step 2: Browse your plans.
The sidebar shows all .md files in the pinned folder, sorted by date. Recent plans float to the top. Click one to render it instantly — headings are headings, code blocks have syntax highlighting, lists are indented properly.
Step 3: Compare plans side by side.
If Claude Code has written multiple plans (say, one for the frontend and one for the backend), open them in separate tabs. MDHero supports tabs natively, so you can flip between plans or drag a tab to split the view. This is particularly useful when you’re reviewing a multi-step refactor and want to cross-reference the plan against the actual changes.
The workflow in practice
Here’s what this looks like day-to-day:
- You give Claude Code a task in the terminal.
- Claude writes a plan to
~/.claude/plans/. - You glance at MDHero’s sidebar — the new plan appears.
- You click it, spend 30 seconds reading the rendered plan.
- You go back to the terminal, approve the plan, and let Claude execute.
- When reviewing the code later, you open the plan again to check whether the implementation matched the intent.
That step 4 is the key moment. Reading the plan before Claude starts coding means you catch bad architecture decisions early — before they’re spread across twelve files. It’s the difference between a five-second “wait, don’t do that” and a twenty-minute rollback.
View Claude Code output: paste and render Claude response in MDHero
Plans aren’t the only Claude Code markdown you’ll deal with. When Claude Code gives you a long response in the terminal — an explanation, a debugging analysis, a list of recommendations — that response is also markdown. But in the terminal, it’s rendered with basic ANSI formatting at best.
If you want to view Claude Code output properly and render Claude response text the way it was written:
- Select the response in your terminal and copy it.
- In MDHero, hit Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows).
- MDHero opens a new tab with the pasted content rendered as markdown.
This is MDHero’s LLM paste mode — effectively a purpose-built llm markdown viewer for terminal-copied AI output. It handles the quirks of terminal-copied text — escaped newlines, mangled code fences, weird spacing — and renders clean markdown. The same trick works for fixing AI paste formatting when you copy from ChatGPT, Gemini, or any LLM that responds in markdown.
Not just for Claude
LLM paste mode works with any markdown-formatted text you copy. ChatGPT responses, GitHub issue bodies, Notion exports — anything that’s markdown under the hood renders correctly when pasted into MDHero.
Other ways to read Claude Code plans
For completeness, here are the alternatives and why MDHero is faster for this specific job:
| Method | Works? | Downside |
|---|---|---|
cat in terminal | Yes | No formatting, no syntax highlighting, scrolls past |
| VS Code preview | Yes | Launches a full IDE, loads workspace, slow for reading |
| GitHub Gist | Yes | Requires uploading a local file to the internet |
| Obsidian | Yes | Requires adding ~/.claude to your vault, heavy setup |
| Browser extension | Partially | Needs “allow file URLs” permission, inconsistent rendering |
| MDHero | Yes | Pin once, read forever. Sub-second open. |
The point isn’t that the other tools can’t do it. They can. The point is that MDHero does it with the least friction. Pin the folder once, and every future plan is one click away, rendered with full formatting, in an app that opens before your finger leaves the trackpad. If you’re weighing other options, see our comparison of free markdown reader and viewer apps for 2026.
Why this matters more than it seems
Claude Code plans are an underrated resource. They’re essentially design documents written by an AI that’s about to implement the design. Reading them gives you:
- Visibility into what Claude is about to change and why
- A review checkpoint before code gets written, not after
- Documentation that you didn’t have to write yourself
- A trail you can revisit weeks later when you’ve forgotten why a module was restructured
Most developers let Claude Code run and review the diff afterward. That works. But reading the plan first is faster feedback. It takes 30 seconds and saves you from approving an approach you’d reject in review.
The plans are already there, sitting in ~/.claude/plans/, written in markdown, waiting to be read. All you need is something that renders them properly.