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+Tabcyclesdefault→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+Tabdoes nothing, a terminal multiplexer or IDE is intercepting it. Use--permission-mode planordefaultModeinstead. - 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+Tabcyclesdefault→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./planprefixed to a prompt plans that single turn. Using/planin Claude Code is the right choice when you want one considered answer without changing the session's mode.claude --permission-mode planstarts the whole session in it. The same flag works with-pfor 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 mode | Presses to plan | Sequence |
|---|---|---|
default (Manual) | 2 | default → acceptEdits → plan |
acceptEdits | 1 | acceptEdits → plan |
plan | 0 | already there |
bypassPermissions or auto | 1–2 | wraps 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:
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:
| Mode | Status bar |
|---|---|
default | manual mode on |
acceptEdits | accept edits on |
plan | plan mode on |
bypassPermissions | bypass permissions on |
auto | auto 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:
| Environment | What happens | Fallback |
|---|---|---|
| tmux | Bound to previous-window, or the back-tab sequence is filtered | claude --permission-mode plan, or set permissions.defaultMode |
| GNU screen | Caught by screen's own keytable | claude --permission-mode plan |
| VS Code integrated terminal | Shift+Tab bound to a workbench command | Use the extension's mode picker, or claudeCode.initialPermissionMode |
| JetBrains terminal | IDE keymap intercepts it for un-indent | Run claude in an external terminal, or --permission-mode plan |
| iTerm2 (custom key profile) | Remapped to an escape sequence iTerm sends itself | Reset 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:
| Surface | Control | Scope |
|---|---|---|
| CLI | Shift+Tab cycle | Session, until changed |
| CLI | /plan prefix | One turn |
| CLI | --permission-mode plan | Session |
| Any | defaultMode in settings | Persistent |
| VS Code | Mode indicator | Session |
| VS Code | claudeCode.initialPermissionMode | Persistent |
| JetBrains | IDE terminal, same as CLI | Session |
| Desktop | Mode selector | Current session |
| Web and mobile | Mode dropdown | Session |
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 label | Mode |
|---|---|
| Manual | default |
| Edit automatically | acceptEdits |
| Plan | plan |
| Auto | auto |
| Bypass permissions | bypassPermissions |
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 type | Modes offered |
|---|---|
| Cloud sessions | Accept edits, Plan, Auto |
| Remote Control | Manual, 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:
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:
| Option | What it does |
|---|---|
| Yes, and use auto mode | Approves and runs with classifier review instead of prompts |
| Yes, manually approve edits | Approves and reviews every edit individually |
| No, refine with Ultraplan | Sends the draft to a browser session for review |
| No, keep planning | Stays 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:
| Kind | How | Keeps the plan? | Lands you in |
|---|---|---|---|
| Discard | Shift+Tab past plan | No — discarded silently | Next mode in the cycle |
| Discard | Esc at the approval prompt | No | Still in plan (dismisses the proposal only) |
| Approve | Yes, and use auto mode | Yes | auto (or acceptEdits / bypassPermissions) |
| Approve | Yes, manually approve edits | Yes | default (Manual) |
| Refine | No, keep planning / refine with Ultraplan | Yes, as working state | Still 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:
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 reads | When | Lands you in |
|---|---|---|
| Yes, and use auto mode | Auto mode is available | auto |
| Yes, auto-accept edits | Auto mode is not available | acceptEdits |
| Yes, and bypass permissions | Session started with bypass enabled | bypassPermissions |
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:
{
"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 first | Go straight to editing |
|---|---|
| You don't know which files are involved | You know the file and the change |
| The change touches a boundary or a shared type | The change is local and reversible |
| Several approaches exist and they diverge | One obvious approach |
| The repo has rules you keep re-explaining | You'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:
{
"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:
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+Tabpresses without checking the start mode. If a previous press left you inacceptEdits, 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 planordefaultModeand stop relying on the key. - Typing
/visual-planand 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+Tabor prefix with/plan. Cycling out instead discards the plan unless you saved it — there is no plan file anywhere on disk. - Confusing
Escwith an exit.Escdismisses the proposal and leaves you in plan mode. To leave the mode you still need aShift+Tabor 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?
Why is Shift+Tab not switching to plan mode?
How do I use plan mode in Claude Code for VS Code?
How do I exit plan mode, and which mode am I in afterwards?
How do I cancel a plan without leaving plan mode?
Can Claude still run commands in plan mode?
Muhammad Kashif
Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.



