How do I start Claude Code in plan mode?

claude --permission-mode plan

Or press Shift+Tab in a running session.

Answer

Run claude --permission-mode plan, or press Shift+Tab in a running session to cycle into it. Claude reads files and explores, then writes a plan instead of editing. Approving it asks which mode to continue in, auto or manual approval of each edit, and exits plan mode; Shift+Tab leaves without approving.

What it does

Plan mode separates working out what to do from doing it. Claude reads files and runs commands to explore, then writes a proposed plan rather than editing your source.

claude --permission-mode plan

File edits are blocked until you approve. Shell commands outside the built-in read-only set, meaning ls, cat, grep, find and about a dozen more, either prompt you, or go to the classifier, the second model that reviews actions in your place, when auto mode is available during planning. The useAutoModeDuringPlan setting controls that second path and allows it by default. On v2.1.212 through v2.1.217 every such command prompted regardless.

The one case where the block does not hold is a session with bypass permissions available. Claude is still instructed to plan rather than edit, but an edit or shell command it attempts anyway runs without prompting. Only explicit ask rules and removals aimed at a critical path, such as / or your home directory, still stop it.

What happens when you approve

The plan arrives with a question rather than a confirmation. You choose:

Yes, and use auto mode — approve, and continue with the classifier reviewing actions. Where auto mode is unavailable this option reads Yes, auto-accept edits; in a bypass session, Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session.
Yes, manually approve edits — approve, and review each edit yourself.
No, keep planning — stay in plan mode and say what to change.

So the mode you land in is your choice, made at that prompt. Either approval exits plan mode on its own; there is no switching back manually. Before you choose, Ctrl+G opens the plan in your text editor, so you can edit it directly rather than describe the change.

When to use it

The extra step pays off when a wrong edit is expensive to unwind:

unfamiliar code, where you want to see the intended change before it lands
work touching several files, where a partial edit is worse than none
a task you described loosely and want to check was understood correctly

The plan is also a cheap correction point. Redirecting a proposal costs a sentence; undoing a set of applied edits costs a revert and a re-read.

When not to use it

Skip it for changes you would not review anyway: a typo, a version bump, a one-line fix you have already located. The plan step adds a round trip and tells you nothing you did not know.

For repetitive mechanical work across many files, acceptEdits fits better: it auto-approves edits and a small set of filesystem commands while still prompting for other commands.

Example

Start a session in plan mode:

claude --permission-mode plan

Make it the default for a project in .claude/settings.json, or for every session in ~/.claude/settings.json; plan applies from either file:

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

VS Code ignores the project file when choosing the starting mode. There, set claudeCode.initialPermissionMode to plan in the extension's user settings instead.

Inside a running session, Shift+Tab cycles into plan mode. Pressing it again while in plan mode leaves without approving the plan, which is how you back out of a plan you no longer want. For a single prompt, prefix it with /plan instead of switching the whole session.

Common mistakes

Expecting Shift+Tab to reach every mode. Plan mode is always in the cycle, but not every mode is: some join only under conditions, and dontAsk never appears at all. Start a session in it instead. See which modes are in the Shift+Tab cycle for the order and the conditions.

Treating it as read-only. Claude still runs shell commands to explore. Those are exploration commands, not edits, but they are not nothing on a system where side effects matter.

Approving a plan you skimmed. The plan is the review step. Approving it without reading moves you to an approval mode with the review already spent.

Trying to switch back manually after approving. Approval exits plan mode by design. If you want to plan again, re-enter it with Shift+Tab, or prefix the next prompt with /plan.