Claude Code plan mode: how to use it

What is plan mode in Claude Code?

Plan mode is one of Claude Code's permission modes. In it, Claude reads files, runs shell commands to explore, and writes a plan, but it does not edit your source. Per the official permission modes page, edits stay blocked until you approve the plan. As of October 2026, that is the whole idea: look first, change later, with you in the loop between the two.

That makes it the cheapest safety net in the tool. If Claude misunderstood the task, you find out from a paragraph of text, not from a diff touching twelve files. If you are new to Claude Code, the Claude Code tutorial covers the basic session first.

The modes are covered in full in the Claude Code permissions guide and the auto mode guide. This page stays on plan mode.

How do you turn on plan mode?

There are three ways, and they all end at the same state: the status bar under the prompt shows ⏸ plan mode on.

1. Press `Shift+Tab` during a session. Each press cycles the permission mode. According to the docs, from auto the first press goes to default, then the cycle runs default, acceptEdits, plan. Optional modes such as bypassPermissions and auto slot in after plan, so watch the status bar rather than counting presses.
2. Prefix one prompt with `/plan`. The commands reference describes /plan [description] as entering plan mode directly from the prompt. Add a description to start immediately, for example /plan fix the auth bug.
3. Start the session in plan mode. Run claude --permission-mode plan from your shell. The same flag works with -p for non-interactive runs.

To leave plan mode without approving anything, press Shift+Tab again. In the VS Code extension, click the mode indicator at the bottom of the prompt box instead.

# inside a session
Shift+Tab           (repeat until the status bar says: plan mode on)
/plan               (switch to plan mode)
/plan add a dark mode toggle to the settings page

# from your shell
claude --permission-mode plan
claude -p "outline how to add rate limiting" --permission-mode plan

What can Claude do while it is planning?

Claude can read your files, search the codebase and run shell commands to learn how things work. It cannot edit your source. When Claude needs to understand a large codebase, the subagents documentation says it delegates the research to the built-in Plan subagent, so the exploration output stays in a separate context window while your main conversation stays read-only. The subagents guide explains how that works.

What happens to a shell command during planning depends on your session. The docs apply the first case that matches:

• Interactive terminal with bypass permissions available: neither the classifier nor a prompt applies to planning commands.
• Auto mode available and `useAutoModeDuringPlan` on (the default): a classifier reviews shell commands other than critical-path removals instead of prompting you. Approved commands run; rejected ones are blocked.
• Auto mode unavailable, or `useAutoModeDuringPlan` off: commands outside the built-in read-only set prompt for approval.

What happens when the plan is ready?

Claude presents the plan and asks how to proceed. The official docs list these choices:

Approving exits plan mode and switches the session to the permission mode the option describes, so Claude starts editing. To plan again, press Shift+Tab back to plan mode or put /plan in front of your next prompt.

Two details are easy to miss. Press Ctrl+G to open the proposed plan in your default text editor and edit it yourself before Claude proceeds. And when the showClearContextOnPlanAccept setting is enabled, the list gains a first option that approves the plan and clears the planning context. Accepting a plan also gives the session a generated title based on the plan, unless you already named it.

Treat the approval screen as a review, not a formality. Read the file list first. If the plan touches files you did not expect, choose No, keep planning and say why.

Can you make plan mode the default?

Yes. Set defaultMode to plan in the project's .claude/settings.json and every terminal session in that project starts in plan mode. According to the docs, project settings honor every value except auto and bypassPermissions, so plan works there.

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

Conversations the VS Code extension starts do not read project settings for the starting permission mode. There, set claudeCode.initialPermissionMode to plan in your VS Code user settings. For one machine instead of one project, put the same permissions.defaultMode in ~/.claude/settings.json; if several files set it, settings precedence decides and a project or managed value outranks your user file.

Starting every session in plan mode suits people who are learning, working in an unfamiliar codebase, or making changes where a wrong edit is expensive. For small edits it adds one approval click each time, so many people leave the default alone and press Shift+Tab when a task is big enough to deserve a plan.

When should you use plan mode, and when should you skip it?

The docs do not give a rule for this, so what follows is editorial judgment. The test is simple: could a wrong first move cost you more than a minute of reading?

Plan mode also pairs with a written spec. The official best practices page suggests asking Claude to interview you when you have not thought a feature through, then write the answers to a SPEC.md file, and starting a fresh session to build from it. Plan mode is a good place to run that interview, because Claude cannot start building mid-conversation.

If you are exploring what to build in the first place, the guide to building an app with Claude Code walks through a full project, and the Claude Code workflow guide shows where planning fits in a day of work.

What should you ask for in a plan?

Claude writes a plan from whatever you give it, so a specific request gets a specific plan. Ask for the things that let you judge the plan quickly: the files involved, the order of steps, what is out of scope, and how each step will be checked. Here is a template you can paste after switching to plan mode.

I want to [one sentence: what the change does for the user].

Before writing any code, give me a plan:
1. The files you expect to create or change, one line each on why.
2. The steps in order, each small enough to review on its own.
3. What is out of scope for this change.
4. Anything you are unsure about, as questions for me.
5. How you will check each step worked (the exact command or test).

Constraints: [libraries to use or avoid, patterns to copy from existing files].
Do not start on step 1 until I approve.

For a practice run, take a small idea such as Meeting cost ticker, posted on the board, and ask for a plan only. Compare the plan with what you would have built. The board has more small ideas, and each one has a generated build prompt you can adapt.

How does plan mode work with subagents and agent teams?

Plan mode carries into delegated work. According to the subagents docs, when the main conversation is in plan mode, a subagent stays in plan mode whichever permissionMode its definition sets. That keeps a research helper from editing files while you are still deciding.

Agent teams, an experimental feature, add one twist. A teammate that Claude spawns while the lead is in plan mode works in read-only plan mode until its plan is ready, then sends a plan approval request to the lead. The agent teams page notes that if you have not changed that teammate's permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it. The agent teams guide covers the details.

Why is Claude editing files in plan mode?

• Check the status bar. If it does not say ⏸ plan mode on, you are in another mode. Cycling with Shift+Tab can pass over plan mode if optional modes are enabled.
• You approved the plan. Approval is the moment plan mode ends, by design. Press Shift+Tab back to plan mode or use /plan to plan the next step.
• Bypass permissions is in your mode cycle. The docs say plan mode's blocks are not enforced in interactive terminal sessions started that way.
• You are in an unexpected client. The VS Code extension reads its own setting, claudeCode.initialPermissionMode, not your project's .claude/settings.json.