Claude Code plan mode: decide before the agent writes

There is one moment in an agent session where stopping is free.

It is the plan approval prompt. A document on screen, four options underneath it, and not a single byte changed on disk. Everything past that point costs something to undo: a diff to read, a branch to reset, a migration to run backwards.

Plan mode exists to make that moment happen on purpose instead of by luck.

Generating code got cheap. Deciding what to build stayed expensive, and will stay expensive, because that half requires knowing your own system. Plan mode is where you spend the expensive half while it is still refundable.

How to use plan mode in Claude Code ​

Four ways in, and they suit different moods:

• Shift+Tab cycles default → acceptEdits → plan. The status bar shows ⏸ plan mode on.
• Prefix a single prompt with /plan when you want one planned turn and nothing more.
• claude --permission-mode plan to start a session there.
• "permissions": { "defaultMode": "plan" } in .claude/settings.json to make it the way a project always opens.

Press Shift+Tab again to leave without approving anything.

The part worth updating your mental model for: the plan is a file now. Claude writes it to ~/.claude/plans/ under a generated three-word name, or wherever you point plansDirectory in your settings. ExitPlanMode will not even fire without one. Try it and the tool answers No plan found. Please write your plan to the plan file first.

That is a bigger change than it sounds. A plan you approve in a chat bubble is gone by tomorrow. A plan on disk is a document you can open, edit, diff and hand to a session that has never heard of this conversation. It is the spec you were never going to write, produced by the thing that is about to implement it.

What plan mode actually blocks ​

Here is the instruction Claude receives, verbatim, from the 2.1.220 binary:

Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.

Followed by the carve-out:

You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.

So the popular description of plan mode, an enforced read-only state where every write tool is disabled, is out of date in three specific ways.

It writes. One file, deliberately, but the write path is open.

It runs shell commands. Exploration needs git log and grep and your test runner's help output. Since 2.1.218 the useAutoModeDuringPlan setting is on by default, which sends those commands to the auto-mode classifier rather than prompting you for each one. Approved commands run during planning.

And in a session where bypass permissions is available, plan mode's blocks are not enforced at all. The docs are blunt about it: Claude is still instructed to plan without editing, but an edit it attempts during planning goes through. If you launched with --dangerously-skip-permissions and then cycled into plan mode for safety, you bought a strongly worded suggestion. Which mode you are actually in depends on how the session started, so it is worth having the permission model in your head before you rely on this one.

Plan mode still earns its place. In an ordinary session the enforcement is real and it holds. Know which guarantee you have, though, because what you are here for is the pause, and the pause survives either way.

The five phases you never see ​

Approving a plan feels like reading one document. Producing it runs a workflow that Claude Code injects into the session and never shows you:

1. Initial understanding. Up to a handful of Explore subagents launched in parallel, one per area of uncertainty, told to hunt for existing functions and patterns to reuse before anyone proposes new code.
2. Design. Plan agents, again in parallel, each handed a deliberately different perspective. The prompt suggests the axes by task type: simplicity against performance against maintainability for a new feature, root cause against workaround against prevention for a bug, minimal change against clean architecture for a refactor.
3. Review. Read the critical files identified during exploration, check the designs against what you actually asked for.
4. Clarify. Ask you real questions through AskUserQuestion, with an explicit ban on using it to ask "is this plan okay?"
5. Call ExitPlanMode.

Some sessions get a leaner variant of the first two phases, where Claude reads the files itself instead of delegating. The shape holds either way.

The plan file has a spec too. It opens with a Context section explaining why the change is being made, carries the recommended approach on its own rather than a menu of alternatives, and names the critical files along with the existing utilities to reuse, paths included. It closes with a verification section describing how to test the change end to end.

Two consequences worth sitting with.

Planning is the most token-expensive stretch of a session, by design. Several subagents reading your codebase in parallel costs real tokens. It is still the correct place to spend, because it is the only spend you can throw away without losing anything.

And subagents cannot plan. EnterPlanMode is refused in agent contexts outright. Planning is a main-thread activity, which means it is a you-and-the-agent activity, which is the entire point.

Getting value out of it ​

Press Ctrl+G. It opens the proposed plan in your editor so you can change it before Claude proceeds, and almost nobody presses it. Reading a plan in a scrolling terminal encourages skimming for vibes. Reading it in your editor encourages the question that matters: whether step four is going to touch the one module you know is fragile.

Reject with feedback rather than approving and steering. "No, keep planning" hands your comments back into the same session with the exploration still loaded. Approving and then course-correcting three edits later means arguing with an agent that is already committed, and paying for the code it wrote on the way.

Point plansDirectory at the repo for anything a colleague will review. ./docs/plans turns the plan into a reviewable artefact that arrives before the pull request rather than after it.

Rewrite the workflow if it does not fit you. --plan-mode-instructions, or planModeInstructions in the SDK, replaces the phase body with your own. The read-only preamble and the ExitPlanMode protocol are always kept, so you can change how it plans without being able to disarm it.

Skip it for small work. Claude Code's own guidance is to skip planning for typos, single-line fixes, a function with clear requirements, and pure research. Planning a two-line change is theatre, and theatre is how a good habit turns into a thing people click through. The prior question is whether the task belongs to an agent at all, which is a different filter and worth applying first.

The approval is the whole feature ​

Everything above is machinery. The feature is the four seconds where you decide.

I have watched myself approve a plan because it was long, well formatted, and arrived while I was thinking about something else. Length reads as diligence. It is not. A plan can name eleven files and still be wrong about the one that matters, and I would not have known, because I read the shape of it and not the content.

That failure has a name in every other part of the job. Approving a plan you did not read is merging code you did not read, moved one step earlier and made cheaper. The cheapness is the good news: the earlier the read happens, the less it costs to say no. This is the same discipline as the rest of the loop, just at the point where saying no is still free.

Plan mode buys you a document, a pause, and somebody else's first draft of the reasoning. The decision stays where it always was. What you do in that pause is the job.