Claude Code plan mode: how to turn it on and use it

Claude Code plan mode is a permission mode where Claude reads and explores your project, then writes a plan instead of editing your source. Permission modes docs The one command is claude --permission-mode plan. In a session that is already running, press Shift+Tab until the status bar shows plan mode on. Common workflows docs

Below are the steps in order, what Claude can and cannot do while planning, how approval works, and the cases where the mode ends up somewhere other than where you expected, with the symptom that tells each case apart.

How do you start plan mode?

Anthropic's permission modes page gives three ways to enter plan mode. Which one fits depends on whether you are launching Claude Code, already inside a session, or only want planning for a single prompt.

1. At launch, run claude --permission-mode plan. The page lists this under "Explore before changing anything" and says Claude Code blocks edits until you approve a plan. Permission modes docs
2. In a running session, press Shift+Tab until the status bar shows plan mode on, preceded by a pause symbol. Common workflows docs
3. For one prompt only, begin the prompt with /plan. Permission modes docs

A first run from a clean terminal follows the same path the common workflows page uses for its codebase overview recipe.

1. Open a terminal and change to the project root with cd /path/to/project, replacing the path with your own. Common workflows docs
2. Start Claude Code in plan mode with claude --permission-mode plan. Permission modes docs
3. Check the status bar for plan mode on. If it shows another mode, the next section explains how the cycle works.
4. Ask something that needs reading before it needs writing, for example find the files that handle user authentication, which is one of the page's recipes for locating code. Common workflows docs
5. Read the plan Claude presents and decide how to proceed. Approval is covered in its own section below.

Other surfaces have their own control for the same mode. Each item below comes from the permission modes page. Permission modes docs

• VS Code: click the mode indicator at the bottom of the prompt box and pick Plan.
• Desktop app: use the mode selector next to the send button in the Code tab.
• Web and mobile: use the mode dropdown next to the prompt box on claude.ai/code or in the mobile app. Cloud sessions list Accept edits, Plan and Auto.
• JetBrains: the plugin runs Claude Code in the IDE terminal, so Shift+Tab and --permission-mode work as in the CLI.

How can you tell plan mode is on?

The status bar is the only indicator the docs name for the CLI. For plan mode it reads plan mode on, with a pause symbol in front. The other modes have their own text: manual mode on for default, accept edits on, auto mode on, don't ask on, and bypass permissions on. Permission modes docs The common workflows page repeats that the status bar shows plan mode on while plan mode is active. Common workflows docs

Pressing Shift+Tab cycles through modes in a fixed order. The permission modes page says the cycle runs default, then acceptEdits, then plan. From auto mode the first press switches to default, so a session that started in auto needs three presses to reach plan. The page's clip of a session that started in auto shows the status bar going from auto mode on to manual mode on, then accept edits on, then plan mode on, then back to auto mode on. Permission modes docs

Some modes sit in the cycle only under certain conditions, and that changes what comes after plan.

• auto appears when auto mode is available, and cycling to it switches without a confirmation prompt. Permission modes docs
• bypassPermissions appears only after you start with --permission-mode bypassPermissions, --dangerously-skip-permissions, --allow-dangerously-skip-permissions, or the matching permissions.defaultMode setting. Permission modes docs
• dontAsk never appears in the cycle and is set with --permission-mode dontAsk. Permission modes docs

Enabled optional modes slot in after plan, with bypassPermissions first and auto last. If you have both enabled, you pass through bypassPermissions on the way to auto. Permission modes docs The practical rule is to keep pressing and read the status bar after each press rather than counting presses.

What can Claude do while planning?

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. Permission modes docs The common workflows page puts the same idea as a way to review changes before they touch disk, with no edits until you approve. Common workflows docs

Edits stay blocked until you approve the plan, with one exception the docs name: interactive terminal sessions where bypass permissions are available. In those sessions, neither the classifier nor a prompt applies to planning commands. Permission modes docs

What happens to a shell command during planning depends on the session. The page says the first case that matches applies.

1. Interactive terminal session with bypass permissions available: no classifier and no prompt for planning commands. A few things still prompt, listed under the bypassPermissions section of the page.
2. 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. Approved commands run and rejected ones are blocked.
3. Auto mode not available, or useAutoModeDuringPlan off: commands outside the built-in read-only set prompt for approval, including when the sandbox's auto-allow mode is enabled.

All three cases are from the same page. Permission modes docs

Two limits apply in every mode. Writes to protected paths are never auto-approved, except in bypassPermissions mode and in plan-mode sessions where bypass permissions are available. Deny rules block in every mode, including bypassPermissions. Permission modes docs The permission modes table describes plan as reads, plus classifier-approved commands when auto mode is available.

How do you approve a plan?

When the plan is ready, Claude presents it and asks how to proceed. The first option the page names is "Yes, and use auto mode", which approves the plan and starts in auto mode. If auto mode is not available to your session, for example because your organization turned it off, that option reads "Yes, auto-accept edits" instead. Permission modes docs

The copy of the permission modes page read for this guide ends partway through that list of choices, so any further options are not reproduced here. The common workflows page points to the Plan mode section of the docs for the approval flow and for editing the plan in your text editor. Common workflows docs

To leave plan mode without approving anything, press Shift+Tab again. Permission modes docs The status bar then shows whichever mode comes next in the cycle, so check it before typing the next prompt.

The neighbouring mode in the cycle is acceptEdits. It lets Claude create and edit files in your working directory without prompting, and it also auto-approves common filesystem commands such as mkdir, touch, rm, rmdir, mv, cp and sed, only for paths inside your working directory or additionalDirectories. Permission modes docs The page recommends it when you would rather review changes in your editor or with git diff after the fact than approve each edit inline.

Is plan mode the same as auto?

They are separate modes with separate jobs, and the permission modes page lists them side by side. Each row below is what runs without a prompt in that mode and what the page says the mode is best for.

In auto mode, a second model called the classifier reviews actions instead of you. Permission modes docs The two modes meet in one place: while planning, if auto mode is available and useAutoModeDuringPlan is on, that same classifier reviews planning shell commands.

On 6 October 2026, Anthropic's permission modes page said that with Claude Code v2.1.283 or later, auto mode is the built-in starting permission mode for interactive terminal and VS Code sessions. Permission modes docs Plan mode is therefore something you switch into, either with the launch flag or with Shift+Tab. On earlier versions the page says auto is the built-in start only on Pro, Max and Team plans, and it names the first session after an install or upgrade as one that can start in a different mode than the table gives.

How do you plan a refactor?

The common workflows page does not tie its recipes to plan mode by name, but its refactor recipe has the same shape: ask for findings, ask for a proposal, then apply. Its four steps, with the prompts it gives, are these. Common workflows docs

1. Identify legacy code: find deprecated API usage in our codebase
2. Get recommendations: suggest how to refactor utils.js to use modern JavaScript features
3. Apply the changes: refactor utils.js to use ES2024 features while maintaining the same behavior
4. Verify: run tests for the refactored code

The first two steps ask Claude to read and propose, which is the work plan mode allows. The third step is the one that edits files, so in plan mode it is the step that waits for your approval. That mapping is a reading of the two pages together, not something either page states in those words. The page's tips for this recipe are to request backward compatibility when needed and to refactor in small, testable increments. Common workflows docs

The bug-fix recipe works the same way. Share the error with something like I'm seeing an error when I run npm test, ask for options with suggest a few ways to fix the @ts-ignore in user.ts, and only then apply one with update user.ts to add the null check you suggested. The page advises telling Claude the command that reproduces the issue, any steps to reproduce, and whether the error is intermittent or consistent. Common workflows docs

Large codebases add a context cost. The page says exploring one fills your context with file reads, and suggests delegating with a prompt like use a subagent to investigate how our auth system handles token refresh, so the subagent reads files in its own context window and reports a summary. Common workflows docs The page does not say how subagents behave when the parent session is in plan mode.

How do you resume a planned task?

Claude Code saves every conversation locally. Running claude --continue resumes the most recent session in the current directory, and if there is none yet it prints No conversation found to continue and exits. To choose from a list, run claude --resume, or type /resume inside a running session. Common workflows docs

The permission modes page refers to a separate section on which permission mode a resumed session starts in. That section is not in the copy read for this guide, so the page here cannot say which mode a resumed conversation opens in. The safe step is to look at the status bar after resuming and press Shift+Tab until it reads plan mode on if you want planning again. Permission modes docs

The docs describe resuming a conversation. They do not describe a plan as a separate saved object. For what carries over between sessions in general, see Claude Code memory, and for what happens to a plan when a long session is compacted, see why Claude Code forgets the plan.

What goes wrong in plan mode?

Each case below gives what you will see, how to tell it from the others, and what the docs say about the cause.

Shift+Tab lands on the wrong mode. The symptom is a status bar that reads accept edits on, manual mode on or auto mode on rather than plan mode on. The cause is the cycle order and your starting mode. From auto, the first press goes to default; from default the next stops are acceptEdits and then plan. If bypassPermissions or auto is enabled, they come after plan, so one press too many moves you past it. Permission modes docs Read the status bar after each press.

Claude does not edit anything. This is the mode working as described. Edits stay blocked until you approve a plan, except in interactive terminal sessions with bypass permissions available. If the status bar reads plan mode on and nothing changes on disk, approve a plan or leave the mode with Shift+Tab. Permission modes docs The pages do not give an error message for a blocked edit, so the status bar is the reliable signal.

Shell commands prompt you during planning. You see approval prompts for commands that are not in the built-in read-only set. By the three cases in the earlier section, this happens when auto mode is not available to the session or when useAutoModeDuringPlan is off. If you see no prompts at all and commands just run, check whether the session is an interactive terminal one with bypass permissions available, or whether auto mode is on and the classifier is reviewing commands. Permission modes docs

The next conversation is not in plan mode. In the VS Code extension, picking Plan or Bypass permissions applies to that conversation only. In the desktop app, a mode you pick is remembered per folder, and Plan is the exception: it applies to the current session only. Permission modes docs To pin a starting mode in VS Code, set claudeCode.initialPermissionMode in your user settings to default, manual, acceptEdits, plan or bypassPermissions. Permission modes docs

A terminal session starts in a different mode than your settings say. Claude Code takes the starting mode from the first of these that applies: the --permission-mode flag or --dangerously-skip-permissions, then permissions.defaultMode in a settings file, then the built-in default. When several settings files set permissions.defaultMode, precedence decides, so a project or managed value outranks ~/.claude/settings.json. Sessions started in a terminal honor every value in a project's .claude/settings.json except auto and bypassPermissions. Permission modes docs

The docs' example of the setting uses default as the value, in ~/.claude/settings.json, and says the next session shows manual mode on in the status bar. The page's contents list includes a section on setting plan mode as the default, but the copy read for this guide ends before it, so no plan-specific settings example is given here. Permission modes docs

Common questions

What is the Claude Code plan mode shortcut?

Press Shift+Tab in a running session until the status bar shows plan mode on. Common workflows docs To plan for a single prompt, begin it with /plan. Permission modes docs

Does plan mode edit my files?

No. Claude reads files, runs shell commands to explore, and writes a plan, and edits stay blocked until you approve the plan. The exception is interactive terminal sessions where bypass permissions are available. Permission modes docs

Is plan mode on by default?

The permission modes page lists auto as the built-in starting mode for terminal and VS Code sessions with Claude Code v2.1.283 or later, with default on some setups, so plan is chosen by you. You can start in it with claude --permission-mode plan or a settings value. Permission modes docs

Can plan mode be used in a script?

The page says the same --permission-mode flag works with -p for non-interactive runs. It does not describe what plan mode does in such a run, so check the docs for your version before relying on it. Permission modes docs

How we checked

This page is a reading of two Anthropic documentation pages, the permission modes page and the common workflows page, on 6 October 2026. Nothing described here was run, tried or tested by the publisher, and no count or experiment sits behind it.

The copy of the permission modes page that was read ends partway through the plan approval options, so the remaining approval choices and the section on setting plan mode as the default are not covered. Where a statement joins the two pages, the text says so.

Last verified 6 October 2026. Both Anthropic pages were read on 6 October 2026, and the permission modes copy ended partway through the plan approval options.

Sources

1. Anthropic, choose a permission mode checked 6 October 2026
2. Anthropic, common workflows checked 6 October 2026

From the publisher

Mover (our product)

Plan mode gives you a plan to review inside one session; if you want that plan kept in plain files on your own computer, loaded into each session, with a warning when your work drifts from it, Mover is a $49 one-time planning tool that runs inside Claude Code or Codex.

Mover is a $49 one-time planning tool that runs inside Claude Code or Codex, keeps your plan in plain files on your own computer, and says so when your work drifts from it. It is the wrong choice if you want something that keeps running while your computer is off.

Get Mover, $49 once

One payment. 30-day money-back guarantee.