Claude Code plan mode: review the plan before any file is touched

Claude Code Published: Updated:

How to enter plan mode in Claude Code, how it differs from the other permission modes, the path from an approved plan to the code, and when a plan is worth the extra step.

Verified on Oct 21, 2026 These tools change quickly. Please also check the latest official documentation. How articles are researched and verified
Contents
  1. Where plan sits among the permission modes
  2. Three ways in
    1. 1. Shift+Tab
    2. 2. A launch flag
    3. 3. Make it the default
  3. From plan to implementation
  4. Where plan mode pays off
  5. Writing a prompt that produces a usable plan
  6. Summary

You ask for a refactor and come back to a large diff heading somewhere you didn't intend. Everyone using Claude Code hits that once. Plan mode is the answer to it.

In plan mode, Claude reads and investigates, then stops at presenting an implementation plan. You read the plan, correct it, and only then let the work start — which matters more the larger the change.

KEY POINT

What you will learn

  • Three ways into plan mode, and how it differs from the other modes
  • The path from a plan to an implementation
  • Where a plan earns its extra step, and where it doesn't

Where plan sits among the permission modes

Claude Code's permission modes decide how much runs without asking you.

ModeFile readsFile editsCommands
planAutomaticNot allowedNot allowed, though classifier-approved commands run where auto mode is available
default (Manual)AutomaticAsksAsks
acceptEditsAutomaticAutomaticAsks, except common filesystem commands such as mkdir, touch, mv and cp
autoAutomaticReviewed by a classifierReviewed by a classifier
dontAskAutomatic, inside your working directoriesPre-approved tools only; anything that would prompt is deniedPre-approved tools only; anything that would prompt is denied
bypassPermissionsAutomaticAutomaticAutomatic, for isolated environments only

Plan mode is the read-only one. That also makes it a good fit for work that shouldn't change anything at all: investigation, design, review. For the full behavior of each mode, including which ones a project settings file can't set, see Changing Claude Code's default permission mode.

Three ways in

1. Shift+Tab

Pressing Shift+Tab in a session cycles through the modes. The current mode shows below the input box, so press until it reads plan. This is the quickest route.

2. A launch flag

claude --permission-mode plan

Use it for a session you want to start by investigating.

3. Make it the default

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

While you're still building intuition, this is a safe default: every session starts by showing you a plan. For how the permissions block fits together, see Configuring permissions in Claude Code's settings.json.

From plan to implementation

  1. In plan mode, say concretely what you want. For example: "Consolidate the authentication logic into lib/auth.ts and remove the duplication from each API route."
  2. Claude reads the relevant files and presents a plan: which files it will change, in what order, and what it is unsure about.
  3. Read it, and reply with corrections. For example: "Leave middleware.ts alone this time."
  4. Once the plan is right, take the option to proceed. The session switches to a mode that can edit, and the work begins.
  5. Afterwards, compare the diff against the plan and check nothing was missed.

用語解説

What a good plan contains: the files it will change, the files it decided not to change, the order, and the risks. A plan with no filenames in it is too abstract — ask it to enumerate the target files.

Where plan mode pays off

  • Changes spanning several files: refactors, API redesigns, swapping a dependency
  • Work that needs a design decision first: where something belongs, whether to reuse an existing mechanism or add one
  • Exploring an unfamiliar codebase: finding where a feature lives, without touching it
  • Reviews: reading a diff or a PR and returning findings only

Using plan mode for a one-file fix or a typo only adds a confirmation step. There, acceptEdits gets you there faster.

Writing a prompt that produces a usable plan

The quality of the plan tracks the specificity of the request.

Goal: share the retry logic across the payment paths
Constraints: don't increase calls to the external API; don't modify existing tests
Wanted output: list of files to change, a summary per file, the implementation order, the test approach

Separating goal, constraints and wanted output is what gets all the parts of a plan filled in.

Approving a plan is not approving the diff

An approved plan doesn't guarantee the implementation matches it. After running with acceptEdits especially, check git diff for changes the plan never mentioned.

Summary

  • Plan mode is read-only: it investigates and presents a plan, and changes nothing
  • Enter it with Shift+Tab, --permission-mode plan, or defaultMode: "plan"
  • Use it for multi-file changes and design decisions; skip it for small fixes
  • Write the request as goal, constraints and wanted output to get a plan you can act on

FAQ

Does plan mode leave my files alone?
Yes. Only reads and searches are allowed; no edits and no command execution, so you can hand it investigation and planning safely.
How do I get out of plan mode?
Cycle modes with Shift+Tab, or take the option to proceed that appears once Claude has presented its plan.
Can a session start in plan mode?
Yes: claude --permission-mode plan. Setting permissions.defaultMode to plan in settings.json makes it the default.

Questions & answers

Q. I want a strong model for plan mode and a cheaper one for implementation. Can I set the planning model and the implementation model independently?

Answer by the editorsSource: GitHub anthropics/claude-code Issue #110126

There is exactly one dedicated setting for this, opusplan. No key for naming two arbitrary models independently could be found in the official documentation — but combined with two environment variables, you can effectively get any pair you want.

First, what opusplan is:

  • In plan mode: uses opus for complex reasoning and architecture decisions
  • In execution mode: automatically switches to sonnet for code generation and implementation
claude --model opusplan

You can also set it with /model opusplan or in settings. For the 1M context window across both phases, use opusplan[1m] (setting that with /model requires Claude Code v2.1.265 or later).

Here is the part that answers your question. Which concrete models opus and sonnet resolve to is redirectable, and the documented environment-variable table names opusplan explicitly.

Environment variableDescription
ANTHROPIC_DEFAULT_OPUS_MODEL"The model to use for opus, or for opusplan when Plan Mode is active."
ANTHROPIC_DEFAULT_SONNET_MODEL"The model to use for sonnet, or for opusplan when Plan Mode is not active."

So selecting opusplan and setting those two gives you separate models for planning and for execution.

export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-haiku-5-5
claude --model opusplan

Each value must be "a full model name, or the equivalent identifier for your API provider" — a full name, not an alias.

There is no combined alias other than opusplan

No sonnetplan or haikuplan setting could be found in the official documentation. There is, however, an unnamed equivalent behaviour for Haiku: "A Haiku session that would normally upgrade to Sonnet in plan mode likewise uses the newest permitted Sonnet, and stays on Haiku only when every Sonnet is excluded."

Also, no setting that gives planning and implementation different effort levels could be found. Effort can be set via /effort, the slider in /model, --effort, CLAUDE_CODE_EFFORT_LEVEL, the modelSettings and effortLevel settings keys, Remote Control, and skill or subagent frontmatter. None of those is scoped to the plan phase.

This reaches subagents too: "In plan mode, these subagents run on Opus if you set your session's model to opusplan, or on Sonnet if you set it to haiku." That covers subagents with model: inherit or no model field, the built-in Explore, Plan and general-purpose subagents, and a fork. To hold a particular subagent on a smaller model, set model in its definition.

One note on the source: issue #110126 was closed the same day by its own author as a duplicate of #66903, where the request for two independent keys now lives.

For plan mode itself, see Claude Code plan mode and reviewing the plan before any file is touched.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.