MarkdownPaper Open reader

Guide

How to read the Markdown files AI coding agents write

Checked against each tool's documentation in October 2026.

AI coding agents write a lot of Markdown: plans, specs, notes, summaries and changelogs. The quickest way to read one properly is to open the .md file in a Markdown reader, not in the chat window or the code editor, so the headings, tables, checklists and diagrams show as a page.

4 min read7 sectionsUpdated 1 Oct 2026

On this page

Where agents leave their files

AgentPlans and notes
Claude CodePlan mode writes plans to ~/.claude/plans (the plansDirectory setting)
CursorPlan mode keeps plans in your home folder; Save to workspace moves one into the project
CodexShows its plan in the session; ask it to write one to a file to keep it

Any agent will also write a file when you ask. Asking for the plan in a file, such as PLAN.md in the project, has two benefits: it survives the end of the session, and you can keep it open while the agent works.

What a plan looks like

Most agent plans use the same few pieces: headings for the stages, a checklist of steps, a table of files, and code.

You write

## Plan: add password reset

### Steps

- [x] Add a `reset_tokens` table
- [ ] Email a link that expires after one hour
- [ ] Rate limit requests to 5 per hour

### Files

| File                  | Change          |
| --------------------- | --------------- |
| `db/schema.sql`       | New table       |
| `routes/reset.ts`     | New route       |

You see

Plan: add password reset

Steps

  • Add a reset_tokens table
  • Email a link that expires after one hour
  • Rate limit requests to 5 per hour

Files

FileChange
db/schema.sqlNew table
routes/reset.tsNew route

In a chat window this arrives as one long column. As a page, the checklist, the table and the code are easy to scan.

Three ways to read it

  • In the editor's preview. VS Code and most editors have a Markdown preview beside the file. It works, but it shares the screen with code.
  • In a web reader. Open the file, or paste it, in a reader like MarkdownPaper. It stays on your device. To see the agent's latest changes, open the file again.
  • In a desktop app that follows the file. The page updates each time the agent saves, so you can keep the plan beside the terminal and watch it fill in. The MarkdownPaper desktop app does this.

Review a plan before you accept it

A plan is cheaper to fix than the code it produces. Read it with these questions:

  1. Does it solve the problem you asked about? Agents drift towards a nearby, easier problem.
  2. Are the files the ones you expected? A file you did not expect is worth asking about before it changes.
  3. Is each step something you could check? "Improve error handling" is not a step. "Return 429 after 5 requests an hour" is.
  4. What does it leave out? Tests, data that already exists, and how the change is undone are the usual gaps.
  5. Are the claims true? If it says a function exists or a library supports something, check.

Write your answers into the file or the chat before the agent starts building.

Common problems

  • The plan shows symbols instead of formatting. It is being shown as plain text. Open it in a Markdown preview or reader.
  • A diagram shows as code. It is a Mermaid diagram. Use a reader that draws Mermaid, as this guide explains.
  • The file keeps changing while you read. That is the agent at work. A reader that follows the file keeps up; otherwise reopen it when the agent stops.

Questions

Where does Claude Code save plans?

In ~/.claude/plans by default. The plansDirectory setting changes the folder.

How do I keep an agent's plan as a file?

Ask the agent to write the plan to a Markdown file in the project, such as PLAN.md, and to tick off steps in it as it works.

What is the best way to read a long Markdown file from an AI?

Open it in a Markdown reader rather than a chat window or a plain text editor, so headings, tables and checklists show as a page.

Next