Plan Mode: Architectural Alignment Before Execution
Plan Mode separates the gather phase from the execution phase — Claude reads and reasons freely, but cannot edit files. Use it to align on approach before a single line is changed. This article covers how to enter it, what Claude can and cannot do inside it, and when it's worth the overhead.
Quick Reference
- →Plan Mode = read-only: Claude can read files and run shell commands but cannot edit files
- →Enter via: Shift+Tab (cycles modes), claude --permission-mode plan, or prefix a prompt with /plan
- →Plan Mode produces a written plan for your review before any execution
- →After the plan, you choose: approve (and pick execution mode), refine with feedback, or discard
- →opusplan alias: uses Opus for planning, auto-switches to Sonnet for execution
- →Plan Mode is not a toggle — /plan prefixes a single prompt, Shift+Tab switches the session mode
- →Use Plan Mode before complex multi-file changes, architectural shifts, or anything hard to undo
- →A good plan surfaces wrong assumptions before they become wrong code
In this article
What Plan Mode Is
Plan Mode is a permission mode where Claude Code can gather context freely — reading files, searching code, running commands — but cannot write or edit any files. It produces a written plan for your review, which you can approve, refine, or discard before execution begins.
In the default mode, Claude's gather and act phases are interleaved — it reads a file and immediately edits it, reads another and edits it, building toward the solution incrementally. This is efficient for simple tasks but dangerous for complex ones: you only see the approach after it has already started executing.
Plan Mode inserts a deliberate checkpoint. The gather phase runs to completion, Claude writes out its intended approach in plain language, and you get to see the plan before any file is touched. This one pause prevents a class of problems: misunderstood scope, wrong architectural assumptions, and changes that look locally correct but are globally wrong.
How to Enter Plan Mode
There are three ways to put Claude Code into Plan Mode, and they behave slightly differently:
| Method | Command | Scope |
|---|---|---|
| Keyboard shortcut | Shift+Tab (cycles: default → acceptEdits → plan) | Session-wide |
| CLI flag at startup | claude --permission-mode plan | Session-wide |
| Prompt prefix | /plan do X (prefix a single prompt) | Single prompt only |
Typing /plan alone does nothing. It is a prefix for a single prompt — /plan do X runs that one prompt in read-only plan mode. The session mode stays as-is for all subsequent prompts. For a full session in plan mode, use Shift+Tab or the CLI flag.
What Claude Can and Cannot Do in Plan Mode
| Allowed in Plan Mode | Blocked in Plan Mode |
|---|---|
| Read files (Read tool) | Edit files (Edit tool) |
| Search code (Grep, Glob) | Write new files (Write tool) |
| Run shell commands (read-only: git log, ls, cat) | Notebook edits |
| Fetch web pages and documentation | Any tool that modifies disk state |
| Reason and produce the written plan |
Plan Mode blocks file edits, but it does NOT block all shell commands. Claude can still run commands that read state (git log, npm list, tsc --noEmit). Commands that modify state (npm install, git commit, rm) will still trigger permission prompts as in the default mode.
After Claude presents the plan, you have several options. You can approve and choose which execution mode to use (default, acceptEdits, or bypassPermissions). You can provide feedback and ask Claude to revise the plan. Or you can discard it and try a different approach. The key is that you decide before any file is modified.
The opusplan Model Alias
Claude Code includes a special model alias called opusplan. It uses the Opus model (the most capable, higher-cost model) during the planning phase, then automatically switches to Sonnet for execution. This gives you Opus-quality architectural reasoning without paying Opus prices for every file edit.
opusplan is most valuable for cross-cutting architectural changes — database schema migrations, new authentication flows, major refactors that touch many files. For adding a button or fixing a typo, it is overkill.
When to Use Plan Mode vs Just Asking a Question
Plan Mode adds latency — you wait for the gather phase, read the plan, and then approve. This overhead is worth it in some situations and unnecessary in others.
| Use Plan Mode when... | Skip Plan Mode when... |
|---|---|
| The task touches 5+ files | The task is a single localized change |
| You're unsure where all the affected code lives | You already know the exact files to change |
| The change has hard-to-reverse consequences (schema migration, API breaking change) | The change is easy to revert (adding a component, fixing a typo) |
| Multiple engineers will be affected by the change | Only your local dev environment is affected |
| You want to verify scope before spending tokens on execution | You've done this exact type of change before and trust the approach |
An engineer was asked to 'migrate the user authentication from session cookies to JWT tokens'. Without Plan Mode, Claude started editing the auth middleware immediately — and got three files in before the engineer noticed it was touching the wrong layer. With Plan Mode, the same task produced a written plan that read: 'I'll modify: (1) auth middleware, (2) login/logout handlers, (3) the session store config, (4) frontend token storage.' The engineer caught that point 4 was wrong — they used HttpOnly cookies for security, not localStorage. The correction took 10 seconds. Without the plan, the fix would have been a second round of edits.
Learn this in → Plan Mode surfaces wrong assumptions before they become wrong code.
Best Practices
Do
- ✓Use Plan Mode for any task touching more than 5 files or with hard-to-reverse consequences
- ✓Read the plan carefully — especially the list of files Claude intends to modify
- ✓Use opusplan for architectural decisions where reasoning quality matters most
- ✓Give specific feedback when revising a plan: 'Don't touch the auth layer' is better than 'the plan is wrong'
- ✓Use Shift+Tab to switch modes quickly mid-session as task complexity shifts
Don’t
- ✗Don't use Plan Mode for every task — the overhead is not worth it for simple changes
- ✗Don't approve a plan you don't understand — ask Claude to explain any step that is unclear
- ✗Don't assume the plan list of files is exhaustive — Claude may discover additional files during execution
- ✗Don't use /plan alone — it is a prefix and does nothing by itself
Key Takeaways
- ✓Plan Mode separates gather from execution — Claude reads freely but cannot edit files
- ✓Three ways to enter: Shift+Tab, --permission-mode plan CLI flag, or /plan prompt prefix
- ✓After the plan, you choose how to proceed — approve, refine, or discard
- ✓opusplan uses Opus for planning and Sonnet for execution — best quality at balanced cost
- ✓Use Plan Mode for complex multi-file changes; skip it for simple localized edits
Video on this topic
Claude Code Plan Mode: See the Plan Before the Execution
tiktok