Skip to content

AI CODING ASSISTANTS

Claude Code Plan Mode: When and How to Use It

Claude Code plan mode blocks edits while Claude researches and proposes. Here's how to enter it, the four approve options, and when planning is wasted effort.

Claude Code plan mode is a permission mode that lets Claude read your codebase and propose changes without touching a single file. Press Shift+Tab until the status bar reads ⏸ plan mode on, describe the task, and you get a written plan and four ways to respond to it. This guide covers what it blocks, the decision rule for when planning is worth the extra turn, and the permission-allowlist failure it protects you from — measured against the 70-entry allowlist this repository accumulated by not using it.

Key takeaways

  • Plan mode blocks edits, not exploration. Claude still reads files and runs read-only commands to research.
  • Shift+Tab cycles default → acceptEdits → plan. Pressing it again from plan mode leaves without approving, discarding the plan.
  • Approving a plan exits plan mode into whichever permission mode the approve option describes — planning is a phase, not a persistent setting.
  • If Shift+Tab does nothing, a terminal multiplexer or IDE is intercepting it. Use --permission-mode plan or defaultMode instead.
  • Plan mode pays when the cost of the wrong approach exceeds the cost of an extra turn. For a one-file change you already understand, it is pure overhead.
  • A permission allowlist is not a substitute. This repository's grew to 70 entries, three of which point at a directory the project no longer lives in.

What plan mode actually blocks

Plan mode blocks writes and permits reads. Claude reads files, runs shell commands to explore, and produces a plan, but cannot edit your source until you approve one.

The exception is worth knowing before you rely on it. In sessions where bypass permissions are available, Claude Code does not enforce plan mode's blocks at all — Claude is still instructed to plan without editing, but an edit it attempts during planning will run. Plan mode is a permission boundary in normal sessions and a strong suggestion in bypass sessions.

Shell commands during planning depend on your version and configuration. As of Claude Code v2.1.218, when auto mode is available and the useAutoModeDuringPlan setting is on (detailed in Anthropic's auto mode configuration docs) — it is on by default — a classifier reviews shell commands during planning rather than prompting you. Otherwise, anything outside the built-in read-only set asks for approval.

How to enter and leave Claude Code plan mode

Three ways in from the terminal, one way out without committing to anything. The desktop app, the VS Code extension and claude.ai each expose their own control instead — those are covered in plan mode outside the terminal.

  • Shift+Tab cycles default → acceptEdits → plan. The status bar shows the active mode; plan mode reads ⏸ plan mode on. Two presses from a fresh session, and the count does not change when optional modes are enabled — why, and the terminals that eat the key.
  • /plan prefixed to a prompt plans that single turn. Using /plan in Claude Code is the right choice when you want one considered answer without changing the session's mode.
  • claude --permission-mode plan starts the whole session in it. The same flag works with -p for non-interactive runs, as documented in the Claude Code CLI reference.

Press Shift+Tab again to leave plan mode without approving. The plan is discarded and the session returns to cycling from default. Approving is the other way out, and the two behave very differently — every exit and where it leaves you has its own section below.

One naming detail trips people up in the docs. The mode that reviews every action is labelled Manual in the CLI, but its config value is default — that is what you write in settings files and what hooks and SDK integrations receive. The manual alias is accepted wherever you type the value and requires v2.1.200 or later. From v2.1.203 Manual mode shows a gray ⏸ manual mode on badge in the status bar.

The Shift+Tab shortcut: how many presses reach plan mode

Shift+Tab is the only keyboard shortcut into plan mode, but it is not a key that means plan mode. It advances the permission-mode cycle one step per press, and plan is one stop on that cycle. People search for a "plan mode hotkey" expecting something like Ctrl+P; there isn't one. The modes form a single ordered ring and Shift+Tab is its advance key, so you press it until the status bar says plan mode on, and one more press takes you out again. We measured the behaviour below against Claude Code 2.1.247 on 2026-08-30.

Starting modePresses to planSequence
default (Manual)2default → acceptEdits → plan
acceptEdits1acceptEdits → plan
plan0already there
bypassPermissions or auto1–2wraps forward to default, then in

A fresh session starts in default unless you set defaultMode, so the answer most of the time is two presses.

That count is stable because of where the optional modes go. Three modes are always in the cycle — default, acceptEdits, plan — while bypassPermissions appears only in a session started with its enabling flag, and auto only when your account has auto mode. Both are appended after plan, bypassPermissions first and auto last:

Our verification run
node scripts/check-plan-mode-shortcut.mjs
# → Stock install                    default -> acceptEdits -> plan                        (plan at index 2)
# → Bypass permissions available     default -> acceptEdits -> plan -> bypassPermissions   (plan at index 2)
# → Auto mode available              default -> acceptEdits -> plan -> auto                (plan at index 2)
# → Bypass + auto both available     default -> acceptEdits -> plan -> bypassPermissions -> auto  (plan at index 2)

Plan sits at index 2 in all four. Enabling an optional mode makes the trip back to default longer, but never adds a stop between default and plan, so "two presses from a fresh session" holds regardless of your plan or your flags.

Counting still fails the moment you are not sure which mode you started in. The status bar is unambiguous — each mode has its own readout:

ModeStatus bar
defaultmanual mode on
acceptEditsaccept edits on
planplan mode on
bypassPermissionsbypass permissions on
autoauto mode on

Press Shift+Tab, glance at the bar, stop when it reads plan mode on. Overshooting into bypassPermissions or auto is the most common mistake with this key, and it matters because those modes let edits through without asking.

When Shift+Tab does nothing: terminal conflicts

Shift+Tab is a fragile binding. It travels as the escape sequence ESC [ Z (often called "back-tab"), and several common environments claim it before Claude Code's input handler sees it:

EnvironmentWhat happensFallback
tmuxBound to previous-window, or the back-tab sequence is filteredclaude --permission-mode plan, or set permissions.defaultMode
GNU screenCaught by screen's own keytableclaude --permission-mode plan
VS Code integrated terminalShift+Tab bound to a workbench commandUse the extension's mode picker, or claudeCode.initialPermissionMode
JetBrains terminalIDE keymap intercepts it for un-indentRun claude in an external terminal, or --permission-mode plan
iTerm2 (custom key profile)Remapped to an escape sequence iTerm sends itselfReset the key mapping, or use /plan per turn

On Windows the binding itself is conditional: the keymap resolves the mode-cycling chord to Shift+Tab only when the bundled runtime is new enough, and to Alt+M otherwise — one of several surprises in the full Claude Code keymap.

In every one of these cases the session is fine; the keystroke simply never arrived. The reliable way around all of them is not to use the key: start with claude --permission-mode plan, commit defaultMode: "plan" as shown in making plan mode the default, or prefix /plan to plan a single turn with no keystroke and no mode change at all.

Plan mode in VS Code, JetBrains, desktop and web

Every surface exposes plan mode differently, and the controls differ in how long they last. Checked against Claude Code v2.1.223 in August 2026:

SurfaceControlScope
CLIShift+Tab cycleSession, until changed
CLI/plan prefixOne turn
CLI--permission-mode planSession
AnydefaultMode in settingsPersistent
VS CodeMode indicatorSession
VS CodeclaudeCode.initialPermissionModePersistent
JetBrainsIDE terminal, same as CLISession
DesktopMode selectorCurrent session
Web and mobileMode dropdownSession

VS Code. Click the mode indicator at the bottom of the prompt box and pick Plan. The extension maps its labels to config values rather than showing the raw names:

VS Code labelMode
Manualdefault
Edit automaticallyacceptEdits
Planplan
Autoauto
Bypass permissionsbypassPermissions

Before v2.1.205 the extension labelled plan as Plan mode and auto as Auto mode, so a screenshot in an older tutorial will not match your UI. To start every VS Code session in plan mode, set claudeCode.initialPermissionMode in VS Code settings or use the extension settings panel. That setting does not accept auto; to start in auto mode you set defaultMode in user settings instead.

JetBrains needs no separate instructions. The plugin runs Claude Code in the IDE terminal, so Shift+Tab and --permission-mode work exactly as they do in the CLI — subject to the keymap conflict above.

Desktop. Use the mode selector next to the send button. The desktop app reads the same settings files as the CLI, so defaultMode applies to new local sessions there too; how its per-folder memory treats plan is covered under making plan mode the default.

Web, mobile and Remote Control. Use the mode dropdown next to the prompt box at claude.ai/code or in the mobile app. Which modes appear depends on where the session runs:

Session typeModes offered
Cloud sessionsAccept edits, Plan, Auto
Remote ControlManual, Accept edits, Plan

Cloud sessions pre-approve file edits regardless of mode, which is why the dropdown shows Accept edits where a local session would show Manual. Bypass permissions is not available in cloud sessions at all. Remote Control sessions run on your own machine and are driven from the app; the dropdown reflects the mode the local session is actually in, including a mode you set from the terminal, and updates in both directions. You can also set the starting mode when launching the host:

Terminal
claude remote-control --permission-mode plan

Remote Control requires signing in with a claude.ai account. API keys are not supported for it.

Why /visual-plan is not a built-in command

Search for how to activate plan mode and you will find /visual-plan presented as a Claude Code command. It is not one. It is a third-party skill published by Builder.io that generates plans as MDX with diagrams, interactive API specs, annotated code, and zoomable wireframes, and offers review modes such as UI-first and prototype-first. It appears nowhere in Anthropic's documentation, because it is something you install as a skill rather than something Claude Code ships with.

The built-in equivalents are plan mode itself for terminal review, and ultraplan for reviewing a long plan in a browser with inline comments on individual sections. If you want the richer artifact /visual-plan produces, install it deliberately.

The four approve options

When the plan is ready Claude presents it and asks how to proceed. The options are not interchangeable, and the difference between the first two is the one that matters:

OptionWhat it does
Yes, and use auto modeApproves and runs with classifier review instead of prompts
Yes, manually approve editsApproves and reviews every edit individually
No, refine with UltraplanSends the draft to a browser session for review
No, keep planningStays in plan mode with your feedback

The first option reads Yes, auto-accept edits when auto mode is unavailable to your account, and Yes, and bypass permissions in sessions started with bypass permissions enabled. Same key, materially different consequences — read the label rather than the position. If that first option has changed on you unexpectedly, the cause is usually your model rather than your plan.

Two smaller controls save real time. Ctrl+G opens the proposed plan in your text editor so you can edit it directly before Claude proceeds, which beats a round trip of "change step 4 to…". And enabling showClearContextOnPlanAccept adds a first option that approves the plan and clears the planning context, which matters because research turns are exactly the tokens you don't want carried into execution — one of three ways planning spends tokens.

How to exit plan mode: discard, approve, or keep planning

Every route out of plan mode is one of two kinds, and they are not variations on the same action. Discarding leaves plan mode without approving anything and writes nothing. Approving commits the plan and drops the session into an editing mode. Verified against Claude Code 2.1.247 on 2026-08-30:

KindHowKeeps the plan?Lands you in
DiscardShift+Tab past planNo — discarded silentlyNext mode in the cycle
DiscardEsc at the approval promptNoStill in plan (dismisses the proposal only)
ApproveYes, and use auto modeYesauto (or acceptEdits / bypassPermissions)
ApproveYes, manually approve editsYesdefault (Manual)
RefineNo, keep planning / refine with UltraplanYes, as working stateStill in plan

Discarding. From plan mode, one more Shift+Tab cycles you out. On a stock install that wraps back to the default Manual mode; if bypassPermissions or auto are enabled for the session, it moves to those instead. Either way any plan Claude had proposed is gone.

Approving. The two options that actually exit plan mode are the first two, and the difference between them is the permission mode the session inherits:

Our verification run
node scripts/check-exit-plan-mode.mjs
# → approve  Approve: Yes, and use auto mode        -> auto     [records plan]
# → approve  Approve: Yes, manually approve edits   -> default  [records plan]
# → discard  Shift+Tab (cycle past plan)            -> next mode in cycle
# → discard  Esc at the plan approval prompt        -> plan (proposal dismissed)

The first option's label and destination change with your account and how the session started:

First option readsWhenLands you in
Yes, and use auto modeAuto mode is availableauto
Yes, auto-accept editsAuto mode is not availableacceptEdits
Yes, and bypass permissionsSession started with bypass enabledbypassPermissions

What the session becomes after each of those is compared in auto mode vs plan mode.

Cancelling is not leaving. "Cancel plan" and "exit plan mode" get searched as if they were the same thing. Pressing Esc at the approval prompt, or choosing No, keep planning, dismisses the current proposal and keeps you in plan mode so you can revise the request. There is no separate cancel key that exits plan mode; if you want out without approving, the cancel is the discard — another Shift+Tab.

What approving records. Approving has three side effects beyond the mode change. The session is renamed from the plan content, unless you already set a name with --name or /rename. An ExitPlanMode tool call is recorded in the session transcript — the only exit that leaves any trace. And the session leaves plan mode immediately, with Claude acting on the plan in the mode you chose. The transcripts above bear out how rarely this path is taken: the 4 plan-mode turns produced exactly 1 ExitPlanMode record. Every other time plan mode was entered, it was left by discarding, which is why nothing was written.

What happens to the planning context. By default, approving carries all the exploration that produced the plan into execution — every file Claude read stays in context. This setting changes that:

~/.claude/settings.json
{
  "showClearContextOnPlanAccept": true
}

With it enabled, the approval list gains a first option that approves the plan and clears the planning research context in one step. The plan is the compressed conclusion of that research; the research itself is dead weight once the decision is made, and carrying it forward is exactly the kind of context that shows up as a slow session.

Claude Code plan vs execute: when planning pays

The decision rule: plan when the cost of the wrong approach exceeds the cost of an extra turn. That is it. Everything else is a proxy for that.

In practice the split is clean:

Plan firstGo straight to editing
You don't know which files are involvedYou know the file and the change
The change touches a boundary or a shared typeThe change is local and reversible
Several approaches exist and they divergeOne obvious approach
The repo has rules you keep re-explainingYou've done this exact edit before

The failure mode nobody warns about is planning trivia. A plan for a one-line copy fix costs a full research pass, a written proposal, and an approval turn, to arrive at the edit you would have made immediately. On this site's content work, plan mode earns its keep for anything that touches lib/mdx.ts or the MDX component map, and is pure overhead for prose edits inside an existing article.

Plan mode also pairs with, rather than replaces, a good context file. A plan built on wrong assumptions is still wrong — the repository conventions Claude needs come from a CLAUDE.md that is accurate, and planning happens on top of that.

Making plan mode the default

Set it in .claude/settings.json (documented in Anthropic's Claude directory configuration reference) and commit it, so the whole team starts in plan mode:

.claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

One behaviour to know if your team uses the desktop app: a mode picked in the mode selector is remembered per folder and takes precedence over defaultMode. Plan is the exception — selecting it there applies to the current session only, so a committed defaultMode: "plan" is not silently overridden for good by one person's UI click.

Do not reach for defaultMode: "auto" in project settings as a shortcut. Claude Code v2.1.142 and later deliberately ignore auto from .claude/settings.json and .claude/settings.local.json, so that a repository cannot grant itself auto mode. It belongs in ~/.claude/settings.json or it does nothing, silently. No such restriction applies to plan, because starting in a mode that blocks edits cannot escalate anyone's permissions.

Why a permission allowlist is not a substitute

The alternative to planning is approving — and the honest artifact for this article is what happens when a project leans on approval for months instead.

This repository has no defaultMode set. Every session starts in Manual, and every unfamiliar command produces a prompt, and the natural response to a prompt is "allow and don't ask again." Here is where that ended up:

Terminal
node -e "const a=require('./.claude/settings.local.json').permissions.allow; console.log(a.length)"
# → 70

Seventy entries in .claude/settings.local.json, fifty-six of them Bash(...) patterns. That file was never designed; it accreted, one interruption at a time. Three of the entries are pinned to absolute paths under a scratchpad directory belonging to a project location this repository no longer occupies — dead rules that can never match again and that nobody will ever notice, because a permission rule that fails to match simply produces a prompt.

That is the same decay pattern as a CLAUDE.md rule that outlives the code it described, and it has the same root cause: config written under time pressure, never re-read. Plan mode attacks it from the other side. Instead of widening what runs without asking, it front-loads the decision into one reviewable artifact — you approve an approach once rather than approving fourteen commands as they arrive.

Neither replaces the other. Broad read-only allowlist entries plus plan mode for anything structural is the combination that actually reduces interruptions without growing a seventy-line list of things you once said yes to.

Ultraplan: planning in the cloud

Ultraplan runs plan mode in a Claude Code on the web session instead of your terminal. It is in research preview as of July 2026, and it exists for one specific limitation: the terminal is a bad review surface for a long plan.

Launch it with /ultraplan <prompt>, by including the word "ultraplan" in a normal prompt, or by choosing No, refine with Ultraplan at a local plan's approval dialog. Your CLI shows a status indicator — ◇ ultraplan while drafting, ◆ ultraplan ready when done — and your terminal stays free meanwhile.

The payoff is in review. You highlight a passage and comment on it, rather than replying to the whole plan in prose and hoping the right paragraph changes. When it looks right you choose where it runs: in the cloud session, opening a pull request from the browser, or teleported back to your terminal with three options — implement in the current conversation, start a fresh session with only the plan as context, or save the plan to a file and walk away.

The constraints are real. It requires a Claude Code on the web account and a GitHub repository, and it is unavailable on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, because it runs on Anthropic's own infrastructure.

Common mistakes

  • Planning things you already understand. A plan for a known one-file edit costs three turns to reach the change you'd have made in one. Planning is insurance; do not insure a $2 item.
  • Counting Shift+Tab presses without checking the start mode. If a previous press left you in acceptEdits, two more overshoot plan into an editing mode. Read the status bar.
  • Assuming the key is broken when it is intercepted. tmux, screen, and IDE terminals eat Shift+Tab. Use --permission-mode plan or defaultMode and stop relying on the key.
  • Typing /visual-plan and assuming Claude Code is broken. It is a third-party skill you have to install first.
  • Reading the approve dialog by position. The first option is auto mode, auto-accept edits, or bypass permissions depending on your account and how the session started. Read the label.
  • Expecting plan mode to persist. Approving a plan exits plan mode into an editing mode that depends on the approve option — every exit path and where it leaves you. If you want the next task planned too, cycle back with Shift+Tab or prefix with /plan. Cycling out instead discards the plan unless you saved it — there is no plan file anywhere on disk.
  • Confusing Esc with an exit. Esc dismisses the proposal and leaves you in plan mode. To leave the mode you still need a Shift+Tab or an approval.
  • Trusting plan mode in a bypass session. With bypass permissions available, the blocks are not enforced. The instruction remains; the boundary does not.
  • Treating an allowlist as the fix for interruptions. It works right up until it is seventy entries long and three of them point at a directory that no longer exists.

Conclusion

Turn plan mode on by default for any repository where a wrong approach costs more than a wasted turn — set defaultMode: "plan" in .claude/settings.json and commit it. Skip it for local, reversible edits you have made before. If you find yourself approving the same commands session after session, that is not a signal to widen your allowlist; it is a signal that the work needed a plan. Plan mode is also one of the concrete workflow differences worth weighing in Claude Code vs Cursor, since an editor built around inline suggestions doesn't need an equivalent gate in the same way. For how it sits against the other five permission modes — and why it runs on the same classifier auto mode uses — see auto mode vs plan mode. More on working with agents in AI Coding Assistants. For where plan mode fits alongside CLAUDE.md, hooks, and subagents, see the complete Claude Code guide.

Frequently asked questions

How do I enter plan mode in Claude Code?
Press Shift+Tab to cycle permission modes until the status bar reads plan mode on, or prefix a single prompt with /plan to plan just that one turn. You can also start a session in it with claude --permission-mode plan. Press Shift+Tab again to leave without approving anything, which discards the plan and returns you to your previous mode.
Why is Shift+Tab not switching to plan mode?
Your terminal is probably intercepting the key. tmux, GNU screen, the VS Code integrated terminal, JetBrains terminals, and iTerm2 with a custom key profile can all bind or swallow Shift+Tab before Claude Code sees it. Start the session with claude --permission-mode plan instead, or set permissions.defaultMode to plan.
How do I use plan mode in Claude Code for VS Code?
Click the mode indicator at the bottom of the prompt box and choose Plan. To start every session in it, set claudeCode.initialPermissionMode in your VS Code settings or use the extension settings panel. Before v2.1.205 the extension labeled this option Plan mode rather than Plan.
How do I exit plan mode, and which mode am I in afterwards?
Press Shift+Tab to cycle out without approving, which discards any proposed plan and switches the session to the next mode in the cycle. Or approve a plan: Yes, and use auto mode leaves you in auto mode; Yes, manually approve edits leaves you in the default Manual mode. When auto mode is unavailable the first option reads Yes, auto-accept edits and leaves you in accept-edits mode instead.
How do I cancel a plan without leaving plan mode?
Press Esc at the plan approval prompt, or choose No, keep planning. Both dismiss the current proposal but keep you in plan mode so you can revise the request. Cancelling a plan and leaving plan mode are different actions.
Can Claude still run commands in plan mode?
Yes, read-only exploration runs freely. Claude reads files and runs shell commands to understand the codebase, but cannot edit your source. As of Claude Code v2.1.218, when auto mode is available and useAutoModeDuringPlan is on, a classifier reviews shell commands during planning instead of prompting you. Otherwise commands outside the built-in read-only set ask for approval.

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.