Claude Code plan mode: review the plan before any file is touched
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.
Contents
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.
| Mode | File reads | File edits | Commands |
|---|---|---|---|
plan | Automatic | Not allowed | Not allowed, though classifier-approved commands run where auto mode is available |
default (Manual) | Automatic | Asks | Asks |
acceptEdits | Automatic | Automatic | Asks, except common filesystem commands such as mkdir, touch, mv and cp |
auto | Automatic | Reviewed by a classifier | Reviewed by a classifier |
dontAsk | Automatic, inside your working directories | Pre-approved tools only; anything that would prompt is denied | Pre-approved tools only; anything that would prompt is denied |
bypassPermissions | Automatic | Automatic | Automatic, 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
- In plan mode, say concretely what you want. For example: "Consolidate the authentication logic into
lib/auth.tsand remove the duplication from each API route." - Claude reads the relevant files and presents a plan: which files it will change, in what order, and what it is unsure about.
- Read it, and reply with corrections. For example: "Leave
middleware.tsalone this time." - Once the plan is right, take the option to proceed. The session switches to a mode that can edit, and the work begins.
- 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, ordefaultMode: "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?
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
opusfor complex reasoning and architecture decisions- In execution mode: automatically switches to
sonnetfor 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 variable | Description |
|---|---|
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.