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 — 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 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 it attempts anyway runs without prompting.

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 bypass permissions.

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.

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 anything else.

Example

Start a session in plan mode:

claude --permission-mode plan

Make it your default in ~/.claude/settings.json:

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

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.

Common mistakes

Expecting Shift+Tab to reach every mode. The base cycle covers default, acceptEdits, and plan. Optional modes slot in after plan: bypassPermissions if the session was started with it, then auto where your account qualifies. dontAsk is never in the cycle — start a session in it instead. See how Shift+Tab cycles modes.

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.