Claude Code Plan Mode: How It Works, and When to Skip It

I put Claude Code in plan mode last week to rename a variable. Nine minutes and two screens of markdown later, I had a proposal for a change I could have described in one sentence. That is the part most write-ups on Claude Code plan mode skip: Anthropic documents when to use it and when not to, and the second half is where the time comes back.

This page is the mechanics: how to enter and leave plan mode, what it actually blocks (less than "read-only" suggests), what the four approval options do, and where plans land on disk. Plans come out as plain markdown, so mine end up in MacMD Viewer, the $19.99 one-time viewer I build.

TL;DR: Shift+Tab twice to enter, Shift+Tab again to leave. Plan mode blocks file edits, not shell commands. Plans are written to ~/.claude/plans as markdown and swept after 30 days by default. And Anthropic's own decision rule: if you could describe the diff in one sentence, skip the plan.

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

What Is Claude Code Plan Mode?#

It is a permission mode in which Claude investigates and proposes, and your source stays untouched until you say otherwise. Anthropic's own description, worth quoting whole because the last sentence carries a qualifier people read past:

"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. Except in sessions with bypass permissions available, edits stay blocked until you approve the plan." — Anthropic, permission modes

This assumes Claude Code is already installed and running — if you are starting from nothing, how to use Claude Code on Mac covers the install and the first session.

The distinction that matters is between asking and enforcing. Type "write me a plan first" in any mode and you get a decent document. Plan mode gives you the document plus a gate: edits blocked, an approval dialog with named options, a keystroke that opens the plan in your editor, and a file on disk. The document is the cheap part. The gate is the product.

How Do You Enter and Exit Plan Mode?#

Press Shift+Tab twice. The mode cycle runs default → acceptEdits → plan, so two presses from the default mode land you in planning, and the status bar switches to ⏸ plan mode on. There are four documented ways in:

On Windows there is a fallback: Alt+M cycles modes "when the Node or Bun runtime doesn't enable VT input mode" (interactive mode docs). If Shift+Tab does nothing in your terminal, try that before filing a bug.

Getting out is one keystroke: "Press Shift+Tab again to leave plan mode without approving a plan." Approving also exits — "Approving a plan exits plan mode and switches the session to the permission mode each approve option describes, so Claude starts editing." Approval is not only a yes to the plan, it is a change of posture for everything after it.

One safety detail if you clone other people's repositories: defaultMode accepts auto, but auto is ignored in project and local settings, "so a repository can't grant itself auto mode."

What Does Plan Mode Actually Block?#

File edits to your source. Not shell commands, and that is the most common misconception about the mode. Anthropic's description says it plainly: Claude "runs shell commands to explore" during planning. Plan mode is not a read-only sandbox, it is an edit gate.

What gates those commands depends on one setting: "when auto mode is available and the useAutoModeDuringPlan setting is on, which it is by default, the classifier reviews shell commands during planning instead of prompting you… Otherwise, commands outside the built-in read-only set prompt for approval."

That read-only set never prompts in any mode, and it is short and fixed: ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, and read-only forms of git. The docs note it "is not configurable" (permissions reference).

Then the carve-out, in the same documented sentence as the guarantee:

"In sessions with bypass permissions available, Claude Code also doesn't enforce plan mode's blocks. Claude is still instructed to plan without editing, but a file edit or shell command it attempts during planning runs without prompting."

If you work inside a devcontainer started with bypass permissions, plan mode is advice rather than enforcement. Claude is still told to plan, and usually does, but nothing stops an edit that slips through.

What Happens When You Approve a Plan?#

You get a dialog with four options. The labels are Anthropic's own wording, but the column worth reading is the second one — what each answer turns the session into:

That second column is why approval is not simply a yes to the document. The first option is not a stronger yes than the second — it is a different session for everything that comes after, including work neither of you has thought of yet. Option three hands the draft to Ultraplan, a research preview that moves planning to a Claude Code on the web session so you can "comment on individual sections of the plan instead of replying to the whole thing".

Two extras. Ctrl+G (or the readline-native Ctrl+X Ctrl+E) opens "the proposed plan in your default text editor and edit it directly before Claude proceeds" — the escape hatch from reviewing a multi-screen document in scroll-back. And a fifth option appears at the top of the list if you turn on showClearContextOnPlanAccept, which approves and clears the planning context in one move; it defaults to false.

Reading a four-screen plan properly in those few seconds is where most bad approvals happen. I wrote the Mac reading workflow for exactly that moment: Ctrl+G, QuickLook in Finder, and a window that reloads when the agent redrafts.

Where Does Claude Code Save Its Plans?#

In ~/.claude/plans, as plain .md files with no frontmatter. That default is configurable through the plansDirectory setting, documented as "Customize where plan files are stored. Path is relative to project root" (settings reference). Check yours:

ls ~/.claude/plans | wc -l

Now the part that catches people: those files are not permanent. Claude Code "deletes session files and other application data older than this period at startup", governed by cleanupPeriodDays, whose default is 30 days — and the plans directory is in the swept set (.claude directory reference). A default install gives you roughly a month of plans, not an archive.

My machine returns 363 plans, 357 of them older than 30 days, the oldest dated 20 March 2026. That is not what a normal install looks like. It is what one machine looks like with "cleanupPeriodDays": 99999 in ~/.claude/settings.json, which I set months ago and forgot. Run the command on yours before assuming the history is there.

If a plan is worth keeping, move it rather than disabling the cleanup:

{ "plansDirectory": "./plans" }

Now plans are versioned with the code they describe, reviewable in a PR, and outside the sweep. For the migration you revisit next quarter, that is the difference between a document and a memory.

Does Plan Mode Work Outside the Terminal?#

Yes, on every surface Claude Code ships on, with one quirk on Desktop worth knowing:

The Desktop quirk: a mode you pick in the selector is normally remembered per folder and takes precedence over defaultMode for that folder. "Plan is the exception: picking it applies to the current session only." So Desktop will not silently keep you in planning across sessions the way it keeps other modes.

What Is the Documented Plan-Then-Code Loop?#

Four phases, and Anthropic publishes the prompts for each. The one-line justification from the best practices guide is "Separate research and planning from implementation to avoid solving the wrong problem."

1. Explore. Enter plan mode and point Claude at the territory: read /src/auth and understand how we handle sessions and login.
2. Plan. Ask for the shape of the change: I want to add Google OAuth. What files need to change? What's the session flow? Create a plan. Then Ctrl+G to edit it directly.
3. Implement. Leave plan mode and reference the plan: implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures.
4. Commit. commit with a descriptive message and open a PR

Two additions are worth making. Anthropic suggests review by a second agent — "Use a subagent to review the rate limiter diff against PLAN.md… Report gaps, not style preferences" — and practitioners run the same idea across models: "I use plan mode in claude code, then use gpt-5 in codex to review the plan and identify gaps and feed it back to claude" (config_yml, Hacker News, 24 November 2025). The other is a model split, plan with the expensive model and implement with the cheap one, which the docs back: "Reserve Opus for complex architectural decisions or multi-step reasoning" (managing costs).

Underneath both is a reframe worth adopting: the plan is the deliverable. "It's planning and research and specification that tends to be the hard part" (hombre_fatal, Hacker News, 20 March 2026).

When Should You Skip Plan Mode?#

When you could describe the diff in one sentence. That is Anthropic's own rule, and it is the most useful sentence in the entire plan mode documentation:

"Plan mode is useful, but also adds overhead. For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly. Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan."

Which is the rule I broke with the variable rename. Plan mode earns its overhead on the three cases named there: unfamiliar code, uncertain approach, multiple files. Outside them it turns a thirty-second instruction into a review task.

The cost argument is more honest than the version you usually hear. Anthropic files plan mode under reducing token usage because it prevents "expensive re-work when the initial direction is wrong" — an upstream saving, not a discount. The planning turns cost tokens, and the one hard multiplier in the docs runs the other way: agent teams use "approximately 7x more tokens than standard sessions when teammates run in plan mode", since each teammate keeps its own context window. For scale, Anthropic puts the average across enterprise deployments at about $13 per developer per active day and $150–250 per developer per month. Planning is cheaper than being wrong about a ten-file change, and more expensive than doing a one-line one.

What Plan Mode Doesn't Fix#

It moves the decision earlier. It does not make the decision easier, and three limitations come up repeatedly from daily users.

Plans read better than they are. "Claude makes more detailed plans that seem better if you just skim them, but when analyzed, has a lot of errors, usually" (patates, Hacker News, 9 April 2026). That matches the broadest developer sentiment I know of: in the 2025 Stack Overflow Developer Survey, 66% named "AI solutions that are almost right, but not quite" as their top frustration (n=31,476). Almost-right is what survives a skim, and a well-formatted plan skims beautifully.

A plan is not a spec. "Plan mode is great, but to me that's just prompting your LLM agent of choice to generate an ad-hoc, imprecise, and incomplete spec" (locknitpicker, Hacker News, 18 March 2026). The document reads like a contract and was produced like a guess. That gap is the argument for Ctrl+G and a redraft round over admiring the first draft's formatting.

There is no middle gear. "I feel like a lot of this could be solved by having a mode somewhere between Plan Mode and Execute Mode… I don't want it to go running off and making changes though, and I also don't really want a detailed plan for a chunk of work" (jon-wood, Hacker News, 12 June 2026). Asking a question of a codebase without commissioning a document is a real want, and the nearest documented answer is Manual mode — default in the cycle — where reads run without prompting and every edit stops for approval.

The undo is partial too. /rewind or double-Esc restores conversation and code to a checkpoint, but "checkpoints only track changes made through Claude's file editing tools. Changes made through Bash commands or external processes are not captured. This isn't a replacement for git." Reading before approving is cheaper than unwinding after.

How I Use It#

Terminal on the left two-thirds of the screen, a markdown window on the right third. Plan mode is my default posture for anything touching more than one file, and off for anything I would have said in one line to a person.

When a plan runs longer than a screen I press Ctrl+G and read it as a document, because a plan is structured markdown: headings, numbered phases, file paths in backticks, sometimes a Mermaid diagram of the control flow. Rendered, the structure tells me where to look and a wrong diagram is visible in a second. Raw, every section costs the same attention, which is how section three gets skipped. The same window handles the rest of what an agent leaves behind — CLAUDE.md, specs, generated docs — covered in reading AI markdown output on Mac, or the Cursor viewer setup if that is your side of the fence. If you are still picking a side, the Cursor vs Claude Code comparison lays out how the two agents differ in practice.

The honest limitation: MacMD Viewer cannot edit, so fixing a typo happens in Ctrl+G's editor or in Claude Code. If you want one window that reads and writes, your editor's preview pane is the right answer and the macOS markdown viewer roundup covers the field. If you want a window that cannot modify the plan an agent is about to execute, that constraint is the point.

Frequently Asked Questions#

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

Press Shift+Tab twice from the default mode. The cycle is default → acceptEdits → plan, and the status bar reads ⏸ plan mode on when you arrive. You can also type /plan, optionally with the task attached (/plan fix the auth bug), or start the session with claude --permission-mode plan. To make it the starting posture for a repository, set permissions.defaultMode to plan in .claude/settings.json.

How do I exit plan mode in Claude Code?#

Press Shift+Tab again to leave plan mode without approving a plan. Approving a plan also exits it, and switches the session to whichever permission mode the approve option you picked describes. To plan again afterwards, cycle back with Shift+Tab or prefix your next prompt with /plan.

What does plan mode actually block?#

File edits to your source, not shell commands. Anthropic's description says Claude "runs shell commands to explore" while planning. What gates those commands depends on useAutoModeDuringPlan, on by default, which lets a classifier review them instead of prompting you. In sessions with bypass permissions available, plan mode's blocks are not enforced at all.

Where does Claude Code save its plans?#

In the directory named by plansDirectory, which defaults to ~/.claude/plans. Plans are plain .md files with no frontmatter. Set {"plansDirectory": "./plans"} to keep them in the repository they describe, versioned with the code.

Do Claude Code plans get deleted?#

Yes, by default. Claude Code deletes application data older than cleanupPeriodDays at startup, the default is 30 days, and the plans directory is in that swept set. An untouched install is not an archive. Raise cleanupPeriodDays or point plansDirectory at your repository if you want plans to outlive the month.

Does plan mode use fewer tokens?#

Not per session. Anthropic lists plan mode under reducing token usage because it prevents "expensive re-work when the initial direction is wrong", which is an upstream saving rather than a discount. The planning turns cost tokens, and the one hard multiplier in the docs runs the other way: agent teams use "approximately 7x more tokens than standard sessions when teammates run in plan mode".

Can I edit a Claude Code plan before approving it?#

Yes. Press Ctrl+G at the approval prompt, or the readline-native Ctrl+X Ctrl+E, to open the proposed plan in your default text editor and edit it directly before Claude proceeds. Answering "No, keep planning" is the other route: it holds you in plan mode so you can say what should change and let Claude redraft.

Is plan mode different from asking Claude for a plan?#

Yes, because it is enforced rather than requested. Edits stay blocked until you approve, there is a documented approval dialog with four options, Ctrl+G opens the plan in your editor, the session gets named from the plan content, and the plan lands on disk as a file. Asking for a plan in default mode gets you the document without the gate.

The Short Version#

Two rules cover most of it. Use plan mode when you are uncertain about the approach, the change spans several files, or the code is unfamiliar — and skip it when you could describe the diff in one sentence. Then read the plan before you approve, because approval switches the session's posture and the undo does not cover everything Claude can do.

The rest is configuration, and one line of it matters more than the others: {"plansDirectory": "./plans"} keeps the plans you care about next to the code they describe, instead of in a directory that empties itself every thirty days. MacMD Viewer is $19.99 once if you want them rendered while you read.