Claude Code plan mode: what it is, how to turn it on, and when to use it

Plan mode is a Claude Code permission mode in which Claude researches and proposes changes without making them. It reads files, runs commands to explore, and writes a plan, then waits for you to approve it before touching your code. Turn it on with Shift+Tab (the status bar shows ⏸ plan mode on), with /plan, or by starting claude --permission-mode plan. Use it when you're unsure of the approach or the change spans several files; skip it when you could describe the diff in one sentence. Details are as of Claude Code in October 2026.

What plan mode does

In plan mode Claude can:

• Read any file in the project and search the codebase.
• Run shell commands to explore, such as listing routes or running the tests to see what fails.
• Write the plan to a Markdown file and present it for approval.

What it can't do is edit your source until you approve. How exploratory commands are handled depends on your setup. When auto mode is available, its classifier reviews each shell command during planning instead of prompting you, controlled by the useAutoModeDuringPlan setting, which is on by default. When it isn't, any command outside Claude Code's built-in read-only set asks for your approval.

One exception is worth knowing. In an interactive terminal session started with bypass permissions available (--dangerously-skip-permissions or --allow-dangerously-skip-permissions), plan mode's blocks aren't enforced: Claude is still told to plan, but an edit it attempts during planning runs without asking. If you want planning to be a hard stop, don't combine it with bypass. The skip-permissions guide explains what that flag turns off.

How to enter plan mode

Shift+Tab during a session. It cycles through permission modes. From auto mode, the default starting mode in the terminal on recent versions, the presses go to Manual, then Accept edits, then Plan. The status bar shows ⏸ plan mode on.

The /plan command. /plan switches to plan mode, and /plan with a description starts planning that task right away:

/plan add rate limiting to the public API

A CLI flag. Start a session already in plan mode:

claude --permission-mode plan

As a project default. Put this in .claude/settings.json so every terminal session in the project starts in plan mode:

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

Other surfaces have their own switch. In VS Code, pick Plan from the mode indicator, or set claudeCode.initialPermissionMode to plan in your user settings, since the extension doesn't read the project's starting mode. In the desktop app, picking Plan applies to the current session only. Cloud sessions and the Claude app (for a Remote Control session) also offer Plan in their mode menus.

Review and approve the plan

When the plan is ready, Claude shows it and asks how to continue:

• Yes, and use auto mode: approve and let Claude implement with auto mode reviewing its actions. If auto mode isn't available to you, this reads Yes, auto-accept edits.
• Yes, manually approve edits: approve and review each edit yourself.
• No, keep planning: stay in plan mode and say what to change.

Before you choose, press Ctrl+G to open the plan in your editor and change it directly: cut a step, add a constraint, fix a file name. Whatever is in the file is what Claude implements.

Planning can use a lot of context. With "showClearContextOnPlanAccept": true in your settings, the menu gets a first option that approves the plan and clears the conversation, so implementation starts from the plan alone. Accepting a plan also names the session after it, unless you've named it already.

To plan again later, press Shift+Tab back to plan mode or prefix the next prompt with /plan.

When to use it, and when to skip it

Anthropic's own advice is to plan when you're uncertain about the approach, when the change touches multiple files, or when you don't know the code well. For small, clear changes (a typo, a log line, a rename), planning only adds a round trip. If you could describe the diff in one sentence, ask for it directly.

For bigger work, the documented workflow has four steps: explore, plan, implement, commit. In practice:

/plan read src/auth and explain how sessions and login work today

I want to add Google sign-in. Which files change, what is the session flow,
and what could break? Write the plan.

Then approve, and in the implementation step ask Claude to check its work against the plan:

Implement the plan. Write tests for the callback handler, run the suite and fix failures.

Finish by asking for a commit and a pull request.

Tips for better plans

Ask for the parts you'll check. A plan you can review lists the files to change, the order of the steps, how each step will be tested, the risks, and what's out of scope. Say so in the planning prompt.

Push back before approving. "No, keep planning" is cheap. It costs a turn; a wrong implementation costs a revert. Questions like "what's the simplest version of this?" or "what happens to existing sessions?" often change the plan.

Keep plans in the repository. Plans go to ~/.claude/plans by default. Set "plansDirectory": "./plans" to write them inside the project, where teammates can read them and you can point a later session at one.

Use a stronger model only for planning. /model opusplan uses Opus while in plan mode and switches to Sonnet for implementation.

Plan before you spawn a team. If the lead session is in plan mode when you ask for an agent team, each teammate plans read-only first. Note that the lead approves those plans itself, so give it your criteria in the request.

Get told when a plan is ready. Approving a plan is a permission prompt for the ExitPlanMode tool, so a PermissionRequest hook with that matcher runs the moment a plan waits for you:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [{ "type": "command", "command": "notify-send 'Claude Code' 'A plan is ready for review'" }]
      }
    ]
  }
}

That example uses Linux's notify-send; the notifications guide has macOS and phone versions, and the hooks guide explains how matchers and decisions work. Keep the hook to a notification: a PermissionRequest hook that returns allow for ExitPlanMode approves every plan without you reading it.