A session that starts editing in its second minute has already decided what the task was. If it read the task wrong, the diff is where you find out, not the plan you wish you had written first. Plan mode pulls those two decisions apart: Claude researches and proposes, you read the proposal, and your approval is what moves the session into a mode where edits actually land.
It is one of the six permission modes from module 11, and it has no page of its own. The permission modes page states what it does in three sentences:
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.
Hold on to that middle clause. The Break section at the bottom is entirely about the exception in the third one.
| Mode | What runs without asking | Best for |
|---|---|---|
plan | Reads, plus classifier-approved commands when auto mode is available | Exploring a codebase before changing it |
That is the row as the permission modes page writes it. The classifier is the automatic judge of allow or refuse you met in module 11. Next we look at when it is the thing standing between Claude and your shell.
What actually runs while Claude is planning
Reads always run, that part is boring and reliable. Shell commands are the interesting half, and which of three things happens to them depends on your session:
- Auto mode available,
useAutoModeDuringPlanon, which the permission modes page says is the default: the classifier reviews each shell command instead of prompting you. Approved commands run, rejected ones are blocked. - Otherwise: anything outside the built-in read-only set prompts for approval. That holds even when the sandbox’s auto-allow mode is on, because auto-allow does not widen approvals in plan mode.
- In a session where bypass permissions are available: neither the classifier nor a prompt applies to planning commands.
One version note, quoted rather than measured: in v2.1.212 through v2.1.217, sessions without bypass permissions prompted for every command outside the read-only set, whether or not auto mode was available. If you are on one of those builds and planning feels like a prompt storm, that is why.
Three ways in, and one way back out
Pressing Shift+Tab cycles the mode. From default the cycle runs default, acceptEdits, plan, back to default; from auto the first press lands on default and the cycle goes from there. Optional modes slot in after plan. You know you arrived because the status bar reads ⏸ plan mode on.
The other two routes are a command and a flag. /plan in front of a single prompt enters plan mode for it, and the commands reference gives it an optional argument: /plan fix the auth bug enters plan mode and starts on that task in one line. At startup, claude --permission-mode plan opens the session there, and the same flag works with -p for non-interactive runs.
Out is one keypress. Shift+Tab again leaves plan mode without approving anything, which is exactly what you want when the plan turned out to be a paragraph and you would rather write the change yourself.
Making it the default, and the one place that ignores it
Set defaultMode to plan in .claude/settings.json and a project’s terminal sessions start there. Two facts about that setting decide whether it actually holds.
A mode you pick from the mode selector is remembered per folder and beats defaultMode for that folder. Plan is the exception: picking plan applies to the current session only, so it never becomes a sticky per-folder choice the way the others do.
And conversations started by the VS Code extension do not read project settings for the starting permission mode at all. There you set claudeCode.initialPermissionMode to plan in your VS Code user settings. A defaultMode in the repo that the whole team relies on is doing nothing for the people working in that extension, yes, really.
The three answers, and the mode each one leaves you in
When the plan is ready Claude presents it and asks how to proceed. The list has three entries, and each one is also a decision about what the rest of the session is allowed to do without asking.
flowchart TD enter["Shift+Tab, /plan,<br/>or claude --permission-mode plan"] --> plan["plan mode:<br/>reads and explores,<br/>edits blocked"] plan --> edit["Ctrl+G opens the plan<br/>in your text editor"] edit --> ask["Claude presents the plan<br/>and asks how to proceed"] plan --> ask ask --> a["Yes, and use auto mode"] ask --> b["Yes, manually approve edits"] ask --> c["No, keep planning"] a --> a2["session runs in auto mode"] b --> b2["you review every edit"] c --> plan
| The option | What it does | When the label changes |
|---|---|---|
| Yes, and use auto mode | Approves and starts in auto mode. | Reads Yes, auto-accept edits when auto mode is unavailable. In a session started with bypass permissions enabled it reads Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session. |
| Yes, manually approve edits | Approves and shows you each edit individually. | |
| No, keep planning | Stays in plan mode; you tell Claude what to change. |
Read the middle column again. Approving a plan exits plan mode and switches the session to the permission mode the option describes. The approval is the mode switch, that is the hidden layer most people miss. To plan again afterwards, cycle back with Shift+Tab or prefix your next prompt with /plan.
Two more things happen around that prompt. Ctrl+G opens the proposed plan in your default text editor so you can edit it before Claude proceeds, the cheapest correction available anywhere in this course, because you are changing the instructions rather than the diff. And when the showClearContextOnPlanAccept setting is on, the list gains a first option that approves the plan and clears the planning context. Accepting a plan also gives the session a generated title based on the plan, unless you have already named the session.
Two tools, and two sentences between them
Claude reaches plan mode through tools, and the tools reference gives each one a single row.
| Tool | The whole documented description | Permission required |
|---|---|---|
EnterPlanMode | Switches to plan mode to design an approach before coding | No |
ExitPlanMode | Presents a plan for approval and exits plan mode | Yes |
That is everything that page says about them: no input schema, no behavioural section, no anchor to link to. The permission column is the one detail worth carrying, entering plan mode needs no permission, and the tool that ends it and asks for your approval does. Anything more than these two sentences would be us inventing it, so this page stops here.
Plan one small change
The smallest working artifact on this page is a keypress. Open a real project and press Shift+Tab until the status bar shows ⏸ plan mode on.
Then run the explore step, using the wording the best practices page uses for its own example:
read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.Claude reads files and answers without changing anything. Now ask for the plan:
I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.When the plan appears, press Ctrl+G. Your text editor opens on the proposed plan. Delete a step you disagree with, tighten a vague one, save, and close. Then answer the approval prompt with Yes, manually approve edits, and watch the first edit arrive as a prompt rather than as a fait accompli.
The best practices page is blunt about when to skip all of this, and the sentence is worth taking literally: “If you could describe the diff in one sentence, skip the plan.” Planning earns its overhead when you are uncertain about the approach, when the change touches several files, or when the code is unfamiliar. On a typo it costs you a round trip and buys nothing, that is the tradeoff in one line.
Land a spec in the project you are working in. A spec is a written description of what you are about to build, precise enough that a session with no memory of this conversation could implement it.
Start a session, keep the prompt minimal, and ask Claude to interview you. This is the prompt from the best practices page, with your feature in place of the bracket:
I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.AskUserQuestion is the tool that turns Claude around and puts the questions to you. It is one of the tools the permissions documentation lists as requiring user interaction, so it cannot run past you unanswered. The best practices page says what it asks about: technical implementation, UI/UX, edge cases, concerns, and tradeoffs, the things you had not thought about yet. The answers become SPEC.md in your repository.
Then start a fresh session to execute it. The new session’s context holds the spec and nothing else, which is the point: no exploratory dead ends, no half-abandoned approaches. The best practices page says what separates a spec that works from one that does not: name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works.
Last, review the result against the spec rather than against your memory of it. Ask for a subagent, a second Claude with its own fresh context, so it sees the diff and your criteria and none of the reasoning that produced the change:
Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.All of that is convention, not feature. SPEC.md and PLAN.md are ordinary files a prompt tells Claude to write and a reviewer to check against. Claude Code has no plan-file feature, no --plan-file flag, and no special handling for either name; the research behind this page searched the permission modes, best practices, commands and sessions pages for one and found none. The only file in this territory that Claude Code itself looks for is .claude/loop.md, and that belongs to a different surface. The plan Ctrl+G opens is in memory, not on disk.
One warning that comes with the review step, from the same page: a reviewer prompted to find gaps will usually report some, even when the work is sound, because that is what you asked it for. Tell it to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional.
You treat plan mode as a guarantee that nothing will be written. It is a guarantee in most sessions, and stops being one in a specific, documented case. The permission modes page:
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. Explicit ask rules and
rmandrmdirremovals targeting a critical path still prompt.
“Available” is doing real work in that sentence, and the same page defines it: sessions started in a way that puts bypassPermissions in the mode cycle. You do not have to be in bypass permissions. You have to be one Shift+Tab away from it. The same condition lifts the protected-path rule you learned in module 11: writes to protected paths are never auto-approved except in bypassPermissions mode and in plan-mode sessions where bypass permissions are available.
Walk into it on purpose, in a scratch repository you do not care about. Start a session with bypass permissions available, press Shift+Tab to plan mode, and ask Claude to plan a change to a file that already exists.
Here is what makes it hard to catch. The status bar still reads ⏸ plan mode on. Claude is still instructed to plan without editing, so it usually still behaves like it is planning, and it will describe the change rather than announce it. No prompt appears, because no prompt is meant to appear. Nothing on the screen distinguishes a session where the block holds from a session where it does not.
The only way to see it is to look somewhere other than the transcript. Run git status yourself, while Claude is still planning, before you approve anything. A clean tree means the block held. A modified file means it did not, and the guarantee you were relying on was an instruction to the model all along.
This is the same shape as the hook lesson in module 9 and the deny-rule lesson in module 11. Plan mode blocks edits in the sessions where the enforcement is switched on; where it is not, it is guidance, and guidance is the thing a model can lose an argument with.
Unknown, and this page will not guess. curriculum/research/05-cross-harness-portability.md surveys ten harnesses across instruction files, MCP, commands, hooks, skills, agents and plugins, and says nothing at all about permission modes or an ask-before-editing mode in any of them. That is a gap in our research rather than a finding about those tools: a harness may well have such a mode and this course has not checked. Until someone fetches those docs, treat every claim you read elsewhere about “Cursor’s plan mode” or the equivalent as unverified.
What does travel is the third item on that report’s list of durable concepts, and it is the one this page ends on: instructions are context, not enforcement. Claude Code’s own documentation says it plainly, and the research found the same split in every tool it surveyed. Plan mode is a nice demonstration, because it is both at once. Where the enforcement is on, edits are blocked by the harness. Where bypass permissions are available, the identical mode is a sentence in the system prompt asking Claude not to edit, and it is exactly as reliable as any other sentence you have written for a model. That is it.
Check yourself
- Your session is in plan mode and Claude runs
npm testwithout prompting you. Name the two different session conditions that would each explain that, and the one command you would run to tell them apart. - You pick Yes, and use auto mode. Which permission mode is the session in for the next tool call, and what would you press to get back to planning?
- A teammate sets
defaultModetoplanin the project’s.claude/settings.jsonand reports that half the team never starts in plan mode. Give two reasons from this page that would produce that.