How I Read Claude Code Plans on Mac Before Approving Them

The plan I regret approving was four screens long and I read two of them. Section three mentioned refactoring the licence check "for consistency" while it was in there. I approved at the first prompt, went to make coffee, and came back to a diff touching a file I had no intention of opening that day. I spent an hour undoing forty seconds of not reading.

So this page is not about reading the markdown a coding agent leaves in your repo. It is about how to read Claude Code plans on Mac in the moment before you approve one, while the terminal holds a decision open and you are the only thing between a proposal and a pile of edits. For the artifacts that persist — CLAUDE.md, AGENTS.md, specs, docs an agent wrote last week — the guide to reading Claude Code markdown files is the superset. This one stays on the approval gate. I read plans in MacMD Viewer, the $19.99 one-time viewer I build, because it renders whatever is on disk and cannot write back.

TL;DR: At the plan approval prompt, Ctrl+G opens the proposed plan in your default text editor. That is Anthropic's own escape hatch from reviewing a multi-screen document in scroll-back. On a Mac, pair it with a rendered read: Space on the file in Finder for QuickLook, or a read-only viewer parked beside the terminal that reloads every time the agent redrafts.

This assumes you are already past setup; if not, start with using Claude Code on macOS and come back when plan mode is in front of you.

Everything below was checked against code.claude.com/docs on 26 July 2026, on Claude Code v2.1.220. It ships weekly, so treat the mechanics as current rather than permanent.

How Do I Read a Claude Code Plan on Mac Before Approving It?#

Get it out of the terminal, then read it rendered. Three moves, in the order you need them:

1. Press Ctrl+G at the approval prompt. The docs are explicit: "Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds" (Anthropic, permission modes). The plan becomes a file instead of scroll-back.
2. Read it rendered, not raw. A plan is markdown: headings, nested lists, file paths in backticks, tables of affected modules, sometimes a Mermaid diagram. Rendered, the structure tells you where to look. Raw, every section costs the same attention, which is how section three gets skipped.
3. Keep it open while you go back and forth. Answer "No, keep planning" and the plan gets rewritten. A viewer that watches the file shows you the new draft without you reopening anything.

Reading in a terminal is not impossible. It is that a plan is a structured document and you are deciding about it under time pressure, with the prompt waiting.

What Is Plan Mode Actually Blocking?#

Edits. All of them, until you say otherwise — with one exception worth knowing about. Anthropic's description: "Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source." The enforcement line matters more than the description: "edits stay blocked until you approve the plan" (permission modes docs).

The exception sits in that same sentence and is easy to read past. The blocks hold except in sessions with bypass permissions available. In those, the docs say, Claude Code "doesn't enforce plan mode's blocks" — Claude is still told to plan without editing, but an edit it attempts while planning runs anyway. So if you work in a container started with bypass permissions, plan mode is a convention rather than a gate, and the read-before-approve habit is the only thing left holding the line.

Three documented ways in:

• Press Shift+Tab to cycle modes. The order is default → acceptEdits → plan.
• Prefix a single prompt with /plan.
• Launch the session with claude --permission-mode plan.

While it is on, the status bar reads ⏸ plan mode on. Shift+Tab again leaves plan mode without approving anything, which is the exit worth knowing before you need it. For a repository where a wrong edit is expensive, make planning the default posture with {"permissions": {"defaultMode": "plan"}} in .claude/settings.json.

Why Is Approving a Plan a One-Way Door?#

Because approval is the last cheap moment. After it you are reviewing edits rather than intentions, and the intentions are what were wrong.

The clearest statement of the problem I have read came from a developer comparing plan mode to a more manual loop: "The big difference with the workflow I described is that with that plan mode you don't get to review and correct what happened between steps" (danmaz74, Hacker News, 12 October 2025). That is the trade at the prompt. You approve a multi-step sequence in one keystroke.

And plans are hard to review, which nobody pretends otherwise about:

"It's hard to review a multi-page plan. Making matters worse, if you give it feedback, it would respond with a whole new version of the multi-page plan." — deaux, Hacker News, 3 April 2026

The second sentence is the underestimated part. Feedback does not produce a diff you can scan. It produces another multi-page document, and your attention for it is lower than it was for the first one.

The numbers say the review is worth the minute. In the 2025 Stack Overflow Developer Survey, 66% of developers named "AI solutions that are almost right, but not quite" as their top frustration (n=31,476). Almost-right is precisely what survives a skim. The same survey found 45.2% say debugging AI-generated code costs more time than writing it themselves, so reading the plan is cheaper than debugging its output.

The plan being a file is what saves you here. As one developer put it, you get "a plan file that you can review. And, also important, have another agent review" (hombre_fatal, Hacker News, 7 April 2026).

What Does Ctrl+G Do in the Approval Dialog?#

It moves the plan into your editor before you decide. That is Anthropic's own answer to "this is hard to read here", and the hinge of the whole workflow. The plan stops being terminal output and becomes a document on disk with a path.

The dialog gives you four options by default, worth knowing verbatim because the wording is precise:

1. Yes, and use auto mode — approve and start in auto mode. Reads "Yes, auto-accept edits" when auto mode is unavailable, and "Yes, and bypass permissions" in a session started with those.
2. Yes, manually approve edits — approve, then review each edit individually.
3. No, refine with Ultraplan on Claude Code on the web.
4. No, keep planning — stay in plan mode and tell Claude what to change.

Option two is what you want when the plan is right in outline but you do not trust the details. Option four is the redraft loop, and the reason a file-watching viewer earns its place on the screen. A fifth option, which approves the plan and clears the planning context, appears at the top of the list only if you have turned on showClearContextOnPlanAccept.

Option three routes to Ultraplan, Anthropic's cloud planning surface, labelled a research preview, so behaviour may change and it is not worth building habits on yet. Its own approval dialog has a choice relevant here: Cancel saves the plan to a file without executing it, and Claude prints the file path. The docs do not state that path, so let it tell you rather than guessing.

Where Do Claude Code Plans Live on Disk?#

On current builds, approved plans accumulate as ordinary .md files in ~/.claude/plans/. Check yours:

ls ~/.claude/plans

Mine holds 363 of them, flat, dating back to March 2026, with filenames like reactive-booping-hearth.md. Inside is plain markdown: an H1, ## Context, numbered phases, fenced paths, the occasional table. No frontmatter, so it renders anywhere.

Two things to know before you rely on that archive. First, the folder is documented: the plansDirectory setting in Claude Code's settings reference controls where plan files are stored, and its default is ~/.claude/plans. Second, it is not permanent by default — files in Claude Code's data directories are swept once they are older than cleanupPeriodDays, which defaults to 30 days. My 363-plan archive back to March only exists because I raised that setting; on a stock install you will see roughly the last month. Other users see the folder too — "it's located in ~/.claude/plans/ for me. Actually, there's whole history of plans there" (mnicky, Hacker News, 22 February 2026). Run ls ~/.claude/plans; believe your own output.

How Does QuickLook Fit the Read-Before-Approve Loop?#

It removes the app switch, which is the whole reason people skip the read. Select the .md in Finder, press Space, and the plan renders inline: headings, syntax-highlighted code, tables, Mermaid diagrams. Arrow keys move through a folder of them without opening a window.

macOS ships no markdown QuickLook support of its own, so this needs an app that installs a QuickLook extension. MacMD Viewer's follows the document theme you picked, so the preview is not a white rectangle if you work dark. The full Finder-side workflow is in the Markdown QuickLook guide for Mac.

What About a Plan the Agent Is Still Rewriting?#

That is the "No, keep planning" loop, and where a separate window stops being a nicety. You send feedback, Claude redrafts, the file changes underneath you. A viewer watching the open document reloads it in place. Read-only is doing real work here: no keystroke edits the file the agent is about to execute, and you cannot save a stray character into a plan you are only supposed to be reading.

Mermaid matters more in plans than anywhere else in a repo. Agents emit mermaid fences freely for sequence flows and architecture sketches, and a diagram is the fastest way to see that a plan's control flow is wrong. MacMD renders those fences on open with no extension. VS Code's built-in preview renders none without one, a real gap if the preview pane is your only reading surface. The VS Code markdown workflow covers the setup if that is where you would rather stay.

Which Other Markdown Does Claude Code Leave Behind?#

More than most people have opened. Once the plan is approved, three sets of files are worth knowing.

Auto memory, on by default, is the one I would look at first because almost nobody has. Claude writes notes about your project to ~/.claude/projects/<project>/memory/, with MEMORY.md as an index loaded every session and topic files like debugging.md loaded on demand. Only the first 200 lines or 25 KB of MEMORY.md loads, and <project> derives from the git repo, so every worktree shares one memory directory. Anthropic's framing: "Auto memory files are plain markdown you can edit or delete at any time" (memory docs). Browse them with /memory. Reading what your agent concluded about your codebase is a strange experience the first time.

.claude/rules/ holds markdown discovered recursively, with optional YAML frontmatter carrying a paths: glob so a rule applies only to matching files. A typical layout is code-style.md, testing.md, security.md beside CLAUDE.md, with a user-level equivalent at ~/.claude/rules/.

CLAUDE.md loads from four scopes, broad to specific: managed policy at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, user at ~/.claude/CLAUDE.md, project at ./CLAUDE.md or ./.claude/CLAUDE.md, and gitignored local at ./CLAUDE.local.md. They concatenate rather than override, the docs suggest under 200 lines each, and @path/to/import works to a maximum depth of 4. One detail worth knowing when you read one: block-level HTML comments are stripped before the file enters context but stay visible when you open it. What Claude sees and what you see are not the same document.

A viewer renders these as documents. It does not execute, validate or act on agent instructions. If the markdown you care about came out of a chat window rather than a repo, saving ChatGPT or Claude output as markdown covers that path instead.

Does Claude Code Read AGENTS.md?#

No, and this trips up a lot of people. The documentation says it outright: "Claude Code reads CLAUDE.md, not AGENTS.md" (memory docs).

The confusion is understandable. AGENTS.md calls itself "a README for agents", is "just standard Markdown" with no required fields, and is used by over 60,000 open-source projects (agents.md, retrieved 26 July 2026). Codex, Jules, Zed, Warp, VS Code, Devin, Cursor and Gemini CLI are among the two dozen tools listed as adopters. Claude Code is not among them.

If you already maintain an AGENTS.md, two documented ways to keep one file: import it by putting @AGENTS.md at the top of your CLAUDE.md, or symlink with ln -s AGENTS.md CLAUDE.md. The import is safer on mixed teams, since symlinks need Admin or Developer Mode on Windows. Either way, verify what loaded with /context under Memory files rather than assuming.

My Setup on macOS#

Terminal on the left two-thirds, MacMD Viewer on the right third. MacMD is the default handler for .md, so anything I open from Finder or the command line arrives rendered instead of as an editor tab I then close.

When an approval prompt appears and the plan runs longer than a screen, I press Ctrl+G, read the file properly, and come back with an actual opinion. For a folder of old plans I stay in Finder and use Space.

The honest cost: you cannot fix a typo in MacMD Viewer. It has no editing surface by design, so changes happen in Ctrl+G's editor or in Claude Code itself. If you want one window that reads and writes, this is the wrong tool and your editor's preview pane is the right one. If you want a reading window that structurally cannot modify what an agent is about to run, that constraint is the product. The macOS markdown viewer roundup covers the alternatives.

Frequently Asked Questions#

How do I read a Claude Code plan before approving it?#

At the approval prompt, press Ctrl+G. Anthropic documents this as opening the proposed plan in your default text editor so you can read and edit it before Claude proceeds. On a Mac you can also read it rendered: select the file in Finder and press Space for QuickLook, or open it in a read-only viewer beside the terminal.

How do I turn on plan mode in Claude Code?#

Three documented ways: press Shift+Tab to cycle default → acceptEdits → plan, prefix a single prompt with /plan, or launch with claude --permission-mode plan. The status bar reads ⏸ plan mode on while it is active. Set defaultMode to plan in .claude/settings.json to make it the starting posture for a repository.

Where does Claude Code save its plans?#

Approved plans accumulate as plain .md files in ~/.claude/plans/ — the documented default of the plansDirectory setting. Check yours with ls ~/.claude/plans. Note that Claude Code cleans up files older than cleanupPeriodDays (30 days by default), so old plans only persist if you raise that setting. Ultraplan can also save a plan to a file when you pick Cancel at its approval dialog, and prints the path it used.

What are the four options in the Claude Code plan approval dialog?#

Yes, and use auto mode; Yes, manually approve edits; No, refine with Ultraplan on Claude Code on the web; and No, keep planning. The first reads "Yes, auto-accept edits" when auto mode is unavailable. Choosing "No, keep planning" holds you in plan mode so you can say what should change.

Does Claude Code read AGENTS.md?#

No. Anthropic's memory documentation states that Claude Code reads CLAUDE.md, not AGENTS.md. The documented workarounds are to import it with @AGENTS.md at the top of CLAUDE.md, or to symlink AGENTS.md to CLAUDE.md. Verify which files loaded with /context, under Memory files.

Can I keep a plan open while Claude Code rewrites it?#

Yes, if the viewer watches the file. When you answer "No, keep planning", Claude redrafts the plan and saves over it. MacMD Viewer reloads the open document when another process writes to it, and it is read-only, so nothing in the reading window can edit the file the agent is about to execute.

What is auto memory in Claude Code and where does it live?#

Auto memory is on by default and lets Claude keep notes about your project in ~/.claude/projects/<project>/memory/, with MEMORY.md as the index loaded each session and topic files loaded on demand. Anthropic describes them as plain markdown you can edit or delete at any time. Browse them with /memory.

The Habit Worth Building#

Plan mode already does the hard part: it stops the edits and hands you a document. The failure is downstream, in the forty seconds where a four-screen plan meets a prompt waiting for a keystroke.

Ctrl+G exists because Anthropic knows reading it in place is awkward. On a Mac, take it one step further and read it rendered: Space in Finder, or a viewer beside the terminal that reloads each time the agent redrafts. MacMD Viewer is $19.99 once and does that job and no other. Whichever tool you use, the plan is the cheapest thing you will ever review.