Claude Code plan mode, and what it actually blocks

What plan mode is, and what it stops

Anthropic's own description is short. Plan mode tells Claude to research and propose changes without making them. It reads files, runs shell commands to explore, and writes a plan, but does not edit your source.

The block is a real one, with a stated exception: except in interactive terminal sessions where bypass permissions are available, edits stay blocked until you approve the plan. That exception turns up in a whole class of report that plan mode did not work, and the section further down takes it apart.

Anthropic summarises the mode in one line as reads, plus classifier-approved commands when auto mode is available, and names its use as exploring a codebase before changing anything. Its protected-path rule bends the same way, so writes to directories such as .git and .claude are never auto-approved except in bypass permissions mode and in plan-mode sessions where bypass permissions are available. One exception on Anthropic's list is the current session's own plan files, in ~/.claude/plans/ or in the plansDirectory you set, alongside the other carve-outs it lists for that directory. The list is a set of exceptions, not a promise that every other protected-path write is refused.

There is no single page for plan mode in Anthropic's documentation. Its coverage is spread across the permission-mode page, the command reference, the interactive-mode page and the Agent SDK permissions pages. This guide draws on the first three, and the source list at the foot of the page names which is which.

Getting in, and the two ways out

There are three doors in. Press Shift+Tab to cycle modes until the indicator reads plan. Prefix a single prompt with /plan, and Claude Code enters plan mode and starts on that prompt with the optional description you gave it, as in /plan fix the auth bug. Or start the session there with claude --permission-mode plan.

Leaving is the part worth committing to memory, because the key does two different things depending on when you press it. Press Shift+Tab again during planning and you exit without approving anything. Approve the plan instead and the session leaves plan mode into whichever permission mode that approve option described, so Claude starts editing. To plan again afterwards, cycle back with Shift+Tab or prefix your next prompt with /plan. The cycle runs manual, then accept edits, then plan, then bypass permissions and auto when those are available, and from auto the first press returns you to manual. On Windows, Alt+M does the same job when the Node or Bun runtime does not enable VT input mode.

Picking plan applies to the current session only, per Anthropic's note on the mode. Two settings make it stickier. For a project's terminal sessions, set defaultMode to plan in .claude/settings.json. Conversations the VS Code extension starts do not read project settings for the starting permission mode, so there you set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.

What happens when the plan is ready

Claude presents the plan and asks how to proceed. Three answers are offered. Yes and use auto mode approves it and starts in auto mode. Yes and manually approve edits approves it and walks each edit past you. No and keep planning keeps you where you are so you can say what needs changing. The first option changes its label with the session: it reads Yes, auto-accept edits when auto mode is not available to that session, and Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session when the session was started with bypass permissions enabled. A label that looks wrong is telling you something real about how the session started.

Two smaller things sit on that screen. Ctrl+G opens the proposed plan in your default text editor so you can edit it directly before Claude proceeds, which is often faster than describing the change in prose. With showClearContextOnPlanAccept enabled the list gains a first option that approves the plan and clears the planning context, for when the exploration has done its job and you want the window back. That clear has a known cost: issue 27242, open since February 20, 2026, reports that the cleared exploration conversation is preserved in its own file with no way to review it afterwards, so read the plan before you take that option rather than expecting to go back to the reading that produced it. Accepting a plan also gives the session a generated title based on the plan, unless you had already named it.

What a shell command may do while you plan

This decides whether planning feels responsive or blocked. What happens to a shell command during planning depends on the session, and the first case that matches wins. With bypass permissions available in an interactive terminal, neither the classifier nor a prompt applies to planning commands. With auto mode available and the useAutoModeDuringPlan setting on, which it is by default, the classifier reviews shell commands other than critical-path removals instead of prompting you, so approved commands run and rejected ones are blocked. With auto mode unavailable or that setting off, a command outside the built-in read-only set prompts for approval, and that stays true even when the sandbox's auto-allow mode is enabled.

One more thing crosses this line. The classifier also reviews each message Claude sends to another agent, before Claude Code delivers it, in auto mode and in plan mode while the classifier is reviewing commands. The send review needs Claude Code v2.1.222 or later. It matters if you run several sessions and leave one planning while it talks to the others.

When it edits anyway

Start with the documented cause, because it explains a common class of report and it is not a bug. In interactive terminal sessions where bypass permissions are available, Claude Code does not 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 recognised rm and rmdir removals of a critical path still prompt. Claude Code v2.1.299, on October 14, 2026, added a one-time note to say so when this is about to happen, and the same release fixed a narrower hole where plan mode ran a write that a PreToolUse hook or a mod's tool.check hook had allowed. That note tells you how easy the shape is to miss: a session that can bypass permissions during a turn can bypass them during a plan, and the instruction not to edit is an instruction rather than a gate.

The documentation names no switch that puts the blocks back inside that session shape. The planning section names useAutoModeDuringPlan, which governs how commands are reviewed, and the two settings above that decide where a session starts, and none of them governs the bypass case. If you want plan mode to be a hard gate, the shape to avoid is an interactive terminal session with bypass permissions available.

The second cause is a separate class of report, filed as a bug in Anthropic's tracker. Issue 38255, titled "Plan mode: model made file edits despite plan mode being active", was filed by siah-maraat on March 24, 2026, and is still open. The report describes four Edit calls to a source file while plan mode system reminders were still being injected into tool results. A commenter on the same issue, forreggbor, described the same thing on March 26 while using /model opusplan and switching with Shift+Tab, and added that the plan was never written or displayed. Two things follow from that thread. The mode is an instruction the model can fail to follow, not a wall. And when it fails, it may fail quietly, with no plan produced to approve.

An older report shows the opposite complaint, and it is worth knowing so you can date the advice you read. Issue 5466, "[BUG] Plan Mode can't be used with Bypass Permissions", was filed by heisler98 on August 9, 2025 against Claude Code 1.0.72, when the two could not be combined at all. The current documentation treats them as combinable in an interactive terminal, which is why the same setup now produces complaints in both directions.

The recovery path is checkpoints. Claude Code captures the state of your code before each prompt you send that starts a turn, and keeps file snapshots for the 100 most recent checkpoints in a session. Run /rewind, or press Esc twice with an empty prompt, to open the rewind menu, and pick restore code and conversation, restore conversation, or restore code depending on what you want back.

Checkpoints have holes worth knowing before you rely on one. A file that only Bash commands changed is not tracked and stays as it is, so a script that rewrote a file is outside what a rewind can undo. A subagent's edits are usually not captured in the session's checkpoints: for any subagent other than a foreground forked skill, a rewind restores only the files Claude had already edited in the conversation, and the subagent's edits to other files stay. The remedy Anthropic documents for both is version control, and its own description of checkpoints is session-level recovery rather than a replacement for Git.

Which model does the planning

Planning and editing are different jobs and they do not need the same model. Anthropic ships an alias for exactly this split: opusplan uses Opus during plan mode and switches to Sonnet for execution, pairing the reasoning for the plan with the cheaper model for the code. Select it with /model opusplan, which switches immediately, or run /model with no argument to open the picker, where Enter switches and saves the choice as your default for new sessions and s switches for this session only.

If the plan needs the longer context, opusplan[1m] asks for a million tokens in both phases where they do not already have it. The split is not new. Anthropic shipped it in version 1.0.77 on August 14, 2025, as an Opus Plan Mode setting in /model that runs Opus only in plan mode and Sonnet otherwise, and the alias appears by name from 1.0.88. Issue 15721, "Automatic Model Switching for Plan Mode", filed in December 2025, asked for a configurable split between the planning model and the execution model, and it was closed as completed in August 2026.

Where the blocks still hold

Plan mode keeps its blocks wherever Claude Code runs without an interactive terminal. Anthropic lists non-interactive runs with -p, Agent SDK sessions, and conversations in the VS Code extension's chat panel. In those places --allow-dangerously-skip-permissions makes bypass permissions selectable later, which is the documented way to open the door if you actually want it open. A scheduled run or a script that drives Claude Code through -p is therefore the shape where plan mode is a hard stop rather than an instruction.

One Windows note. Issue 3390, "Shift+Tab not switching to plan mode on Windows", was filed by bukanpeneliti on July 12, 2025 against Claude Code 1.0.51 on Windows 11, and it was closed as a duplicate two days later. If the key appears to do nothing on Windows today, the interactive-mode page's Alt+M fallback is the first thing to try before assuming the mode is broken.

Everything above was read against Claude Code 2.1.310, the newest release on Anthropic's changelog on October 23, 2026. Plan mode has moved several times in the last few months, with two plan-mode entries in 2.1.299 alone, so a tutorial from earlier in the year may describe behaviour the current build does not have.

Where a desktop app puts the plan

Omniscio is the desktop app we make for running Claude Code sessions. A session that stops on a plan does not sit in a terminal you have to find it in: it shows in the session list with a violet dot and the sub-label Plan Review, next to the blue question dot and the cyan permission dot. The state is derived from Claude Code's own ExitPlanMode tool, so it reflects what the CLI actually reported rather than a guess from the text on screen.

Open the session and a banner sits above the composer with two buttons. Approve plan sends the canonical approval, "Approved. Proceed with the plan.", which is the same text the app's auto-approve setting sends, so an approval clicked by hand and one sent automatically are byte-identical to the agent. Request changes sends nothing at all: it puts your cursor in the message box so you can describe the change in your own words, which matters because a plan you disagree with needs a sentence, not a button.

That row comes from Claude Code's ExitPlanMode tool, so it appears for any session on the Claude Code harness, including the Claude-compatible models such as DeepSeek, GLM and Kimi that run through the same path. An engine that reports its own approvals instead does not raise it. The free plan covers 8 projects and 10 agents at once, and Pro is $20/month or $192/year, so running several planning sessions at once is inside the free tier.

Two defaults are worth knowing before you assume one. A per-session spend cap limits only the sessions billed to a pay-per-use API key, and it never limits a Claude Pro or Max subscription session. Worktree isolation is off by default and can be switched on app-wide, per project or per session; engines that run tools outside Claude Code's guardrail hooks, which is Gemini, Grok, Antigravity, OpenCode, Pi, Hermes, Kimi Code and DeepSeek Harness, start isolated by default in a git repository, only a per-session choice turns that off, and a project that is not a git repository always runs in place.

The session statuses page in our documentation covers the whole dot vocabulary, and the parallel agents guide covers running several of these sessions at once. If the plan is the step before a larger build, the orchestration guide puts it among the other jobs a run does, and the features page lists what else is in the app.

Sources

Every Anthropic fact on this page rests on one of these, and the date beside each one is the day we read it. The Omniscio section rests on our own documentation and the defaults in the app, and the rows in the fact ledger beside this page name the file for each claim.

• Choose a permission mode, for what plan mode blocks, the protected-path rules, how to enter and leave it, the approval options, the planning-command cases, the bypass-permissions exception, and the two settings that set a default. Read October 25, 2026.
• Commands, for /plan and its optional description. Read October 25, 2026.
• Interactive mode, for the Shift+Tab mode cycle and the Alt+M fallback on Windows. Read October 25, 2026.
• Model configuration, for the opusplan alias, the 1M variant, and what /model does with and without an argument. Read October 25, 2026.
• Checkpointing, for what a checkpoint captures, the rewind menu, the 100-checkpoint window, and the Bash, subagent and version-control limits. Read October 25, 2026.
• Claude Code changelog, for version 2.1.310 on October 23, 2026 and the two plan-mode entries in 2.1.299. Read October 25, 2026.
• Anthropic's documentation index, for the entry list that establishes there is no single page for plan mode. Read October 25, 2026.
• Session statuses, our own documentation, for the status vocabulary and the dot a waiting session shows. Read October 25, 2026.
• Issue 38255, plan mode: model made file edits despite plan mode being active, filed March 24, 2026. Read October 25, 2026.
• Issue 5466, plan mode can't be used with bypass permissions, filed August 9, 2025. Read October 25, 2026.
• Issue 3390, Shift+Tab not switching to plan mode on Windows, filed July 12, 2025. Read October 25, 2026.
• Issue 15721, automatic model switching for plan mode, filed December 29, 2025. Read October 25, 2026.
• Issue 27242, no way to review context after a plan-mode clear, filed February 20, 2026. Read October 25, 2026.

Anthropic moves both the mode and the wording. The pages above carry version notes such as "requires Claude Code v2.1.222 or later", and the changelog gained two plan-mode entries in a single release this month. Read the source again before you trust a copy of this page from a few months back.

Common questions

What is plan mode in Claude Code?

Plan mode tells Claude to research and propose changes without making them. It reads files, runs shell commands to explore and writes a plan, but does not edit your source, and edits stay blocked until you approve that plan, except in an interactive terminal session where bypass permissions is available.

How do I turn on plan mode?

Press Shift+Tab until the mode indicator reads plan, prefix a single prompt with /plan, or start the session with claude --permission-mode plan. To make it the default for a project, set defaultMode to plan in .claude/settings.json.

How do I get out of plan mode?

Press Shift+Tab again to leave without approving anything. Approving a plan also leaves plan mode and switches the session to the mode that approve option names, so Claude starts editing.

Why did Claude edit files in plan mode?

There are two separate causes. In an interactive terminal session where bypass permissions is available, Claude Code does not enforce plan mode's edit blocks, so a write runs without prompting. Separately, users have filed reports where the model ignored the mode with no bypass involved, which Anthropic tracks as a bug.

What is opusplan?

opusplan is a model alias that uses Opus during plan mode and switches to Sonnet for execution, so the expensive reasoning happens on the plan. Select it with /model opusplan, or /model opusplan[1m] to ask for a million-token context in both phases where they do not already have it.

Does plan mode work in the VS Code extension?

Yes, and the blocks hold there. Anthropic says plan mode keeps its blocks wherever Claude Code runs without an interactive terminal, which includes the VS Code extension's chat panel, non-interactive -p runs and Agent SDK sessions.

How do I make plan mode the default?

Set defaultMode to plan in .claude/settings.json for a project's terminal sessions. Conversations started by the VS Code extension do not read project settings for the starting permission mode, so there the setting is claudeCode.initialPermissionMode in your VS Code user settings.

Where are plan files stored?

In ~/.claude/plans/, or in the plansDirectory you set. Anthropic lists the current session's own plan files there as one of several exceptions to the protected-path rule for that directory.