skip to content

Permission & Plan Modes

Six modes, from Manual and acceptEdits to plan, auto's background classifier and bypassPermissions, switched with Shift+Tab or flags. Asked because the mode sets how far the agent acts without asking.

part ofClaude Coderead it →
on this pageshow

explore

questions

6

In Claude Code, what does plan mode let Claude do, how do you enter it, and what happens when you approve the plan?

level: juniorimportance: must knowfreq 34%

answer

  1. research first, source stays untouched
  2. a key, a slash prefix, a launch flag
  3. /plan takes an optional task description
  4. each approve option names the next mode
  5. Ctrl+G opens the plan in your editor

basics

~20 s

Plan mode lets Claude read files and run exploratory commands to propose a change without editing source. Enter it with Shift+Tab, a /plan prefix or --permission-mode plan; approving the plan exits plan mode into the mode the chosen option names.

solid answer

~50 s

Plan mode is a permission mode in which Claude researches and writes a plan but does not edit your source; edits stay blocked until you approve. You enter it by pressing `Shift+Tab` until the status bar shows `⏸ plan mode on`, by prefixing one prompt with `/plan` (for example `/plan fix the auth bug`), or at launch with `claude --permission-mode plan`. Shell commands during planning are reviewed by the auto-mode classifier when auto mode is available and `useAutoModeDuringPlan` is on (its default); otherwise anything outside the read-only set prompts. When the plan is ready you choose **Yes, and use auto mode** (or **Yes, auto-accept edits** when auto is unavailable), **Yes, manually approve edits**, or **No, keep planning**. Approving leaves plan mode, so to plan the next task you press `Shift+Tab` back or use `/plan` again; `Ctrl+G` lets you edit the plan text before Claude proceeds.

go deeper

for a junior

Recall the three entry points, Shift+Tab, a /plan prefix and --permission-mode plan, and that Claude researches and proposes but does not edit until you approve.

for a middle

Explain what runs during planning: reads always, shell commands through the classifier when auto is available and useAutoModeDuringPlan is on, prompts otherwise.

for a senior

Show you know approval is a mode switch, which option lands where, and that interactive sessions with bypass available stop enforcing plan mode's blocks.

for a principal

Weigh plan mode as a team default in project settings against its cost in round trips, and note the VS Code extension reads its own setting instead.

## What plan mode is Claude Code runs every session in a **permission mode**, a baseline that decides which actions run without asking you. **Plan mode** (config value `plan`) is the one built for looking before touching: Claude reads files, runs shell commands to explore, and writes a proposed plan, but it **does not edit your source**. Edits stay blocked until you approve the plan. The status bar shows `⏸ plan mode on` while it is active. Plan mode is Claude Code's own mechanism. The general argument for planning before acting as an agent design belongs to the agent-planning material; what matters here is the switch, what runs during planning, and what the approval does. ## Entering and leaving plan mode There are three ways in: 1. **`Shift+Tab`** cycles the permission modes. The cycle runs `default` (labelled Manual) to `acceptEdits` to `plan`; from a session that started in `auto`, the first press goes to Manual, so plan is three presses away. 2. **`/plan [description]`** enters plan mode straight from the prompt. With a description, such as `/plan fix the auth bug`, it enters plan mode and starts on that task at once. 3. **`claude --permission-mode plan`** starts the whole session in plan mode. Pressing `Shift+Tab` again leaves plan mode **without** approving a plan. To make plan mode the starting mode for a project's terminal sessions, set `permissions.defaultMode` to `"plan"` in the project's `.claude/settings.json`; the VS Code extension does not read project settings for its starting mode, so there you set `claudeCode.initialPermissionMode` to `plan` in your VS Code user settings instead. ```bash # start a session that cannot edit until a plan is approved claude --permission-mode plan ``` ## What runs while Claude is planning Reads always run. What happens to a shell command depends on the session, and the first matching case applies: | Session | Shell commands during planning | | :- | :- | | Interactive terminal with bypass permissions available | No classifier and no prompt; plan mode's blocks are not enforced | | Auto mode available and `useAutoModeDuringPlan` on (the default) | The classifier reviews them; approved ones run, rejected ones are blocked | | Auto mode unavailable, or `useAutoModeDuringPlan` set to `false` | Anything outside the built-in read-only set prompts you | Removals with `rm` or `rmdir` aimed at a critical path, such as the home directory, are never auto-approved during planning; in a terminal they ask you. ## Approving the plan When the plan is ready, Claude presents it and asks how to proceed: - **Yes, and use auto mode** approves and switches the session to `auto`. If auto mode is not available to the session, for example because an administrator set `disableAutoMode`, this option reads **Yes, auto-accept edits** instead. In a session started with bypass permissions enabled it reads **Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session**. - **Yes, manually approve edits** approves and puts you back to reviewing each edit yourself. - **No, keep planning** keeps plan mode on so you can tell Claude what to change. Before choosing, `Ctrl+G` opens the proposed plan in your default text editor so you can edit it directly. With `showClearContextOnPlanAccept` enabled, the list gains a first option that approves the plan and clears the planning context. Accepting a plan also gives an unnamed session a title generated from the plan. The key point is that **approval is a mode switch**: the session leaves plan mode and lands in whichever mode the option names. Plan mode is not sticky. For the next task you cycle back with `Shift+Tab` or prefix the prompt with `/plan` again. ## Where plan mode's blocks do not hold - In an **interactive terminal session with bypass permissions available** (started with `--dangerously-skip-permissions`, `--allow-dangerously-skip-permissions` and similar), Claude is still instructed to plan without editing, but an edit or command it attempts during planning runs without prompting. Explicit ask rules and critical-path removals still prompt. - Wherever there is no interactive terminal, such as `claude -p`, the Agent SDK and the VS Code chat panel, plan mode keeps its blocks. - Deny rules apply in plan mode as in every mode; the rule grammar itself is a separate subject. ## Why it is asked Plan mode is the cheapest way to see what an agent intends before it changes anything, and the most common misreadings are that it forbids all commands (it does not), that it persists after approval (it does not), and that the only way in is a launch flag (`Shift+Tab` and `/plan` both work mid-session).

  • Why might a shell command run without a prompt while Claude Code is in plan mode?
    When auto mode is available and `useAutoModeDuringPlan` is on, which is the default, the classifier reviews planning commands instead of you, so approved ones run. Set `useAutoModeDuringPlan` to `false` to get prompts instead. In an interactive terminal session with bypass permissions available, plan mode's blocks are not enforced at all.
  • After approving a plan, how do you plan the next task?
    Approval exits plan mode into the mode the option named, so you either press `Shift+Tab` until `⏸ plan mode on` shows again or prefix the next prompt with `/plan`. Pressing `Shift+Tab` from plan mode without approving leaves it with no plan accepted.
  • How do you make every terminal session in one repository start in plan mode?
    Set `permissions.defaultMode` to `"plan"` in that project's `.claude/settings.json`. Terminal sessions honour it; a `--permission-mode` flag still overrides it for one session. The VS Code extension ignores project settings for its starting mode, so there you set `claudeCode.initialPermissionMode` to `plan`.

  • Plan mode stops Claude from running any shell command at all.
  • After you approve, the session stays in plan mode for the next task.
  • The only way into plan mode is starting the session with a flag.
  • Choosing No, keep planning throws the plan away and returns to Manual.
  • Plan mode is a model choice rather than a permission mode.
open as a page

In Claude Code, which permission mode fits a supervised refactor, an unattended overnight task and a read-only audit, and why?

level: middleimportance: must knowfreq 30%

basics

~20 s

Use acceptEdits for a supervised refactor you review by diff, plan for a read-only audit since edits stay blocked, and auto for an overnight task; bypassPermissions belongs only in an isolated container or VM, and deny rules hold in every mode.

open as a page

Since Claude Code v2.1.283, what decides the permission mode a new interactive session starts in, and how does Shift+Tab cycle from there?

level: middleimportance: should knowfreq 14%

basics

~20 s

The --permission-mode flag wins, then permissions.defaultMode from settings, then the built-in default, which is auto for interactive terminal and VS Code sessions since v2.1.283. Shift+Tab goes auto to Manual, then Manual, acceptEdits, plan, with enabled bypass and auto after plan.

open as a page

In Claude Code's auto mode, what does the background classifier review, what still prompts or is blocked, and when does auto mode fall back to prompting?

level: seniorimportance: should knowfreq 16%

basics

~20 s

A separate classifier model reviews actions other than reads and working-directory edits, blocking escalation and unrecognised infrastructure. Ask rules still prompt, deny rules still block, and 3 blocks in a row or 20 in total revert to prompting.

open as a page

Why won't Claude Code auto-approve writes to .git, .claude or .bashrc, even in acceptEdits with an Edit(.claude/**) allow rule?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Those are protected paths: writes to them are never auto-approved, outside bypassPermissions, because they hold repository state, shell startup files and Claude's own configuration. The check runs before allow rules from settings, so Edit(.claude/**) changes nothing.

open as a page

When you resume a Claude Code session with claude --continue, which permission mode does it start in if it ended in plan or bypassPermissions?

level: middleimportance: nice to knowfreq 6%

basics

~10 s

claude --continue normally restores the mode the session ended in, but not plan or bypassPermissions: both start in the mode a new session would start in. Pass --permission-mode or --dangerously-skip-permissions to choose explicitly.

open as a page