Claude Code Plan Mode (2026): How to Turn It On, Approve Plans and When to Use It

Plan mode is a Claude Code permission mode where Claude researches your code and writes a plan but doesn't edit your source files until you approve it. Turn it on by pressing Shift+Tab until the status bar shows ⏸ plan mode on, by starting a prompt with the plan command, or by launching Claude Code with the permission mode set to plan. When the plan is ready you approve it, keep planning, or press Ctrl+G to edit the plan yourself before Claude writes any code.

Checked against Anthropic's Claude Code documentation on October 17, 2026. Claude Code updates often, so labels and defaults can change between versions. If something on your screen looks different, update Claude Code first (see how to update Claude Code).

What plan mode does

Every Claude Code session runs in a permission mode that decides what Claude may do without asking you. Plan mode is the one built for thinking before acting: Claude reads files, runs shell commands to explore, and writes a plan, but it doesn't edit your source. Edits stay blocked until you approve the plan. Anthropic's best-practices guide frames this as separating exploration from execution, so Claude doesn't jump straight into code that solves the wrong problem.

How exploration commands are handled depends on your session. Anthropic documents three cases, and the first one that matches applies:

• Auto mode available and useAutoModeDuringPlan on (the default): the auto mode classifier, a second model, reviews each shell command instead of prompting you. Approved commands run and rejected ones are blocked. Removals that target critical paths still go to you.
• Auto mode not available, or useAutoModeDuringPlan turned off: any command outside Claude Code's built-in read-only set asks for your approval.
• Interactive terminal sessions where bypass permissions is available (you launched with one of the skip-permissions flags or set bypassPermissions as your default mode): plan mode's blocks aren't enforced. Claude is still told to plan without editing, but an edit or command it attempts runs without a prompt. Explicit ask rules and removals of critical paths still prompt.

Plan mode keeps its blocks wherever Claude Code runs without an interactive terminal: non-interactive runs with the print flag, Agent SDK sessions, and conversations in the VS Code extension's chat panel. In the Agent SDK, file edits in plan mode are never auto-approved, even when an allow rule matches or a hook returns allow; they go to your canUseTool callback instead.

With Claude Code v2.1.283 or later, auto mode is the built-in starting mode for interactive terminal and VS Code sessions, so most people reach plan mode by cycling away from auto.

How to enter plan mode

Option 1: Shift+Tab during a session

Press Shift+Tab to cycle permission modes. From auto mode, the first press switches to Manual, and the cycle then runs Manual, accept edits, plan. Optional modes such as bypass permissions and auto come after plan. Keep pressing until the status bar reads ⏸ plan mode on. From a fresh session that starts in auto mode, that's three presses.

On Windows, if Shift+Tab doesn't switch modes, use Alt+M. Anthropic lists it as the alternative when the Node or Bun runtime doesn't enable VT input mode.

Option 2: The plan command

Start a message with the plan command to switch into plan mode from the prompt. With a description after it, Claude enters plan mode and starts planning that task right away:

/plan fix the auth bug

On its own, without a description, the command just switches the session into plan mode and waits for your next message:

/plan

Option 3: Start a session in plan mode

claude --permission-mode plan

The same permission-mode flag works for non-interactive runs, where plan mode's blocks always hold. For example, to get a written plan for a change without letting Claude touch any files:

claude -p --permission-mode plan "Propose a plan to add rate limiting to the /login endpoint"

Option 4: Make plan mode the default for a project

To start every terminal session in a project in plan mode, set defaultMode to plan in the project's .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

The VS Code extension doesn't read a project's settings files for its starting mode. There, set claudeCode.initialPermissionMode to plan in your VS Code user settings, or choose Plan from the mode indicator at the bottom of the prompt box for a single conversation.

{
  "claudeCode.initialPermissionMode": "plan"
}

How to approve, edit or exit a plan

When the plan is ready, Claude shows it and asks how to continue:

• Press Ctrl+G to open the proposed plan in your default text editor and change it directly before Claude proceeds.
• Approving a plan exits plan mode and switches the session to the mode the option names, so Claude starts editing.
• Accepting a plan also gives the session a generated title based on the plan, unless you already named the session.
• To leave plan mode without approving anything, press Shift+Tab again.
• To plan again later, cycle back with Shift+Tab or start your next prompt with the plan command.

Clear the planning context when you approve

Long planning sessions can fill a lot of the context window with file reads. The showClearContextOnPlanAccept setting (off by default) adds a first option to the approval menu, Yes, clear context and …, that approves the plan, clears the conversation, and starts implementing from the plan alone. The label also shows how much context the planning used. Turn it on in your settings file:

{
  "showClearContextOnPlanAccept": true
}

This is useful when the plan is complete enough to stand on its own. If the plan relies on things Claude learned but didn't write down, keep the context instead, or edit the plan with Ctrl+G to add the missing details before you clear.

A worked example: planning a feature

Anthropic's recommended workflow has four phases: explore, plan, implement, commit. Here's how that looks for adding Google sign-in to an existing app.

1. Explore. Enter plan mode and ask Claude to read the relevant code. Nothing gets edited.
2. Plan. Ask for a concrete plan: which files change, in what order, and how you'll test it.
3. Review. Read the plan. Press Ctrl+G to fix anything directly, or choose No, keep planning and say what to change.
4. Implement. Approve with the option that fits how closely you want to watch, then ask Claude to implement and run the tests.
5. Commit. Ask Claude to commit with a descriptive message and open a pull request.

Example prompts for the explore and plan phases, typed while plan mode is on:

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

After you approve, a typical implementation prompt is:

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

What makes a plan worth approving

• It names files. A good plan lists the files it will create or change, not just the idea.
• It states the order of changes, for example the database migration first, then the model, then the API route, then the UI.
• It says how it will verify the work: which tests to add or run, and what command builds or lints the project.
• It flags open questions. If Claude had to guess about something, such as which OAuth library you prefer, answer it before approving instead of after the code is written.
• It stays in scope. If the plan touches files you didn't expect, ask why before approving.

When to use plan mode (and when to skip it)

• Unfamiliar codebases: let Claude map the files and data flow before it touches anything.
• Multi-file changes and refactors: review the order of changes and the affected files up front.
• Risky areas such as authentication, payments, database migrations or deployment config, where you want to read every step before it runs.
• When you're unsure of the approach: ask Claude to compare two or three options in the plan and pick one before any code exists.
• Saving usage: a reviewed plan catches a wrong approach before Claude spends tokens editing and re-editing files. That matters on Pro plan limits or pay-per-token API billing.

Anthropic notes that plan mode adds overhead. For small, clear tasks such as fixing a typo, adding a log line or renaming a variable, ask Claude to do it directly. Their rule of thumb: if you could describe the diff in one sentence, skip the plan.

Plan with Opus, build with Sonnet: the opusplan model setting

Claude Code has a special model alias, opusplan, that uses Opus while you're in plan mode and switches automatically to Sonnet once you approve and execution starts. The idea is to use the stronger reasoning model for architecture decisions and the faster, cheaper one for writing code. Switch to it inside a session:

/model opusplan

Or start a session with it:

claude --model opusplan

The planning phase uses the same context window as the opus model setting, and execution uses the same one as sonnet. If your organization's model allowlist excludes the newest Opus, Anthropic says opusplan plans with the newest Opus you're allowed. On Pro or Max subscriptions, keep in mind that Opus and Sonnet usage can count against different limits; see Claude Code pricing and Claude pricing for the plan details.

Where plans are saved

Claude Code writes plan files to ~/.claude/plans by default. To keep plans inside your repository, for example so they can be reviewed in a pull request, set plansDirectory to a path relative to the project root:

{
  "plansDirectory": "./plans"
}

Claude Code falls back to ~/.claude/plans if the path resolves outside the project root (such as ../plans) or, on macOS, Linux and WSL, if it contains a backslash. Write paths with forward slashes, which also work on Windows.

Plan mode in other Claude Code apps

• VS Code: click the mode indicator at the bottom of the prompt box and choose Plan. Picking Plan there applies to that conversation only; it isn't remembered as your next starting mode.
• JetBrains: the plugin runs Claude Code in the IDE terminal, so Shift+Tab and the permission-mode flag work the same as in the CLI.
• Desktop app: in the Code tab, choose Plan in the mode selector next to the send button. Other modes are remembered per folder, but Plan applies to the current session only.
• Claude Code on the web and mobile: cloud sessions offer Accept edits, Plan and Auto in the mode dropdown. In the mobile app, tap the + button in the prompt box, then Permission.
• Agent SDK: set the permission mode to plan. Claude explores and plans; edits go to your canUseTool callback, and Claude may ask clarifying questions before it finalizes the plan.

The old ultraplan command, which sent a planning task to a cloud session, has been removed. Anthropic's command reference now points to plan mode instead.

Troubleshooting

Shift+Tab doesn't change the mode

• On Windows, try Alt+M. Some Node or Bun runtimes don't enable VT input mode, so the terminal never passes Shift+Tab through.
• Watch the status bar while you press: you may be cycling past plan mode. From auto mode it's three presses to reach plan.
• If a permission prompt is open, Shift+Tab acts on the prompt instead of cycling modes. Answer or close the prompt first.
• Old versions may differ. Update Claude Code and try again.

Claude keeps asking me to approve exploration commands

That means the auto mode classifier isn't reviewing commands for you: either auto mode isn't available to your account, model or organization, or useAutoModeDuringPlan is set to false. Anthropic's settings reference notes that a repository can't turn this setting off for you; it lives in user, local or managed settings. You can approve the commands, add allow rules for ones you trust, or check auto mode availability in Anthropic's permission modes page.

Claude edited files while I was in plan mode

In interactive terminal sessions where bypass permissions is available, plan mode's blocks aren't enforced. If you started with a skip-permissions flag or set bypassPermissions as your default mode, start a fresh session without it when you want a guaranteed read-only planning phase. Plan mode's own plan files are also allowed to be written, so a new file under your plans directory is expected.

My project setting doesn't start VS Code in plan mode

Expected: the extension never reads a project's .claude/settings.json for its starting mode. Use the claudeCode.initialPermissionMode VS Code setting shown above, or pick Plan from the mode indicator.

The plan is too vague or too long

• Choose No, keep planning and ask for specifics: "list every file you'll change and the tests you'll add".
• Narrow the task. One plan per feature works better than one plan for a whole roadmap.
• Point Claude at the right code with @ file references so it doesn't spend context exploring unrelated folders.
• For large codebases, ask Claude to use a subagent for research so only the findings land in your main context.

I approved by mistake

Press Esc to stop Claude mid-turn; it keeps the work done so far. Then press Esc twice at an empty prompt to open the rewind menu and restore code and conversation from an earlier point, or use git to discard changes. Press Shift+Tab to go back to plan mode before continuing.

Costs and which plans include it

Plan mode is a built-in feature of Claude Code, not a paid add-on, so it's available wherever you can use Claude Code: Pro, Max, Team and Enterprise subscriptions, or Claude API billing. Planning still uses tokens, because Claude reads files and reasons about them, but a short plan is usually cheaper than throwing away a wrong implementation. On Enterprise plans and API-billed accounts, Anthropic notes that auto mode classifier checks also count toward token usage. See Claude Code pricing and Claude API pricing for current prices, or is Claude free? for what you can do without paying.

Students and open-source maintainers may qualify for discounted or free access: see the Claude student discount and Claude for Open Source. If you haven't set up Claude Code yet, start with how to install Claude Code, and if you'll use an API key rather than a subscription, see how to get an Anthropic API key.