Claude Code plan mode: what it does, how to use it, and when to skip it
Plan mode tells Claude Code to research and propose changes without making them: it reads files, runs exploratory commands and writes a plan, but does not edit your source until you approve. Turn it on with Shift+Tab, with /plan before one prompt, or with claude --permission-mode plan. Use it for large or ambiguous changes; skip it for small, clear fixes.
What is Claude Code plan mode?
Plan mode is one of Claude Code's permission modes. In the docs' words, it "tells Claude to research and propose changes without making them". Claude reads files, runs shell commands to explore and writes a plan, but your source stays untouched until you approve.
The point is to separate deciding from doing. On a big change, the expensive mistakes come from starting in the wrong direction; plan mode lets you see and correct the direction before a single file changes.
How to turn on plan mode
| How | What it does |
|---|---|
Shift+Tab |
Cycles the permission mode; the status bar shows ⏸ plan mode on |
/plan before a prompt |
Plans just that one request |
claude --permission-mode plan |
Starts the whole session in plan mode |
"defaultMode": "plan" in .claude/settings.json |
Makes plan mode the project's starting mode in the terminal |
Press Shift+Tab again to leave plan mode without approving anything. In VS Code, set claudeCode.initialPermissionMode to plan instead, since the extension doesn't read the project's starting mode.
Reviewing and approving the plan
When the plan is ready, Claude shows it and asks how to proceed:
- Yes, and use auto mode (or Yes, auto-accept edits where auto mode isn't available): approve and let Claude work.
- Yes, manually approve edits: approve, then review each edit.
- No, keep planning: stay in plan mode and say what to change.
Press Ctrl+G to open the plan in your own editor and change it directly before Claude starts. Approving exits plan mode; to plan again, cycle back with Shift+Tab or use /plan.
During planning, exploration commands are handled by the session: where auto mode is available, a classifier reviews them; otherwise anything outside the built-in read-only commands asks for approval.
Claude Code permission modes compared
| Mode | Runs without asking | Best for |
|---|---|---|
default (Manual) |
Reads only | Reviewing every action, sensitive work |
acceptEdits |
Reads, file edits, common file commands | Iterating on code you are reviewing |
plan |
Reads (plus classifier-approved commands where auto mode exists) | Exploring before changing |
auto |
Everything, with background safety checks | Long tasks with fewer prompts |
dontAsk |
Pre-approved tools and reads; everything else denied | Locked-down CI and scripts |
bypassPermissions |
Everything | Isolated containers and VMs only |
Modes are the baseline; permission rules sit on top, and deny rules block in every mode.
When to use plan mode, and when to skip it
Plan first when the change is large or open: several valid approaches, architectural decisions, many files, a library migration, restructuring a service. A wrong first step there costs hours of rework.
Go straight to work when the change is small and clear: a single-file bug fix with a clear stack trace, one added validation check. Planning those adds a step without lowering risk.
The pattern that works best on real projects combines both: plan the migration, approve the plan, then let Claude execute it directly. For the exploration itself, a subagent such as the built-in Explore agent keeps verbose search output out of your main conversation, so the context stays free for the work.
Plan mode on the Claude Certified Architect exam
Task statement 3.4 of the Claude Certified Architect guide is exactly this choice: plan mode for complex tasks with large-scale changes, multiple valid approaches and multi-file modifications; direct execution for simple, well-scoped changes; the Explore subagent to isolate verbose discovery; and plan-then-execute for migrations. Scenario 2, code generation with Claude Code, names "when to use plan mode vs direct execution" in its description.
The trap is to treat plan mode as "the careful choice" for everything. On a one-line fix, the better answer is direct execution.
Related reading: Claude Code hooks for rules that must always run, Claude skills for repeatable workflows, and all articles.
Sources: Choose a permission mode (plan mode, approving a plan, the modes table); Claude Code settings; Claude Certified Architect Foundations exam guide v1.0, task statement 3.4 and scenario 2.
FAQ
How do I turn on plan mode in Claude Code?
Press Shift+Tab to cycle to plan mode (the status bar shows plan mode on), prefix a single prompt with /plan, or start a session with claude --permission-mode plan.
Does Claude Code edit files in plan mode?
No. Claude reads files, runs commands to explore and writes a plan, but source edits stay blocked until you approve the plan. The exception is an interactive terminal session started with bypass permissions available.
Can I change the plan before Claude starts?
Yes. Choose No, keep planning and say what to change, or press Ctrl+G to open the plan in your text editor and edit it directly.
When should I not use plan mode?
For simple, well-scoped changes, such as a single-file bug fix with a clear stack trace. Planning those adds a step without reducing risk.