Claude Code plan mode
By Mari Luukkainen · 4 min read · Last updated
On this page
Plan mode is a Claude Code permission mode in which Claude reads files, explores the project and writes a plan, but cannot edit your source until you approve. Turn it on with Shift+Tab until the status bar shows "plan mode on", start a session with claude --permission-mode plan, or put /plan in front of a single prompt. Facts here come from Anthropic's permission modes docs, checked 11 November 2026.
Permission modes are introduced in what Claude Code is. Plan mode is also a cost habit: a wrong approach caught in a plan costs a few messages, while the same mistake caught after the edits costs a rewrite. Plans and usage limits are compared on Claude Code pricing.
Ask AI about this pageChatGPTClaudePerplexityGoogle AI ModeGrok
How do you turn on plan mode?
| Where | How |
|---|---|
| During a session | Press Shift+Tab. The cycle runs default, acceptEdits, plan; the status bar shows "plan mode on" |
| For one prompt | Start the prompt with /plan |
| When you start Claude Code | claude --permission-mode plan |
| As the default for a project | Set permissions.defaultMode to "plan" in .claude/settings.json |
| In VS Code | Set claudeCode.initialPermissionMode to plan in your VS Code user settings. VS Code sessions do not read the project setting for the starting mode |
If auto mode is on, the first Shift+Tab switches to default, and the cycle continues from there. To leave plan mode without approving anything, press Shift+Tab again (permission modes).
{
"permissions": {
"defaultMode": "plan"
}
}What can Claude do in plan mode?
It can read files, run shell commands to explore and write the plan. It cannot edit your source; edits stay blocked until you approve. Which shell commands run without a prompt depends on your session. When auto mode is available and the useAutoModeDuringPlan setting is on, which is the default, a classifier reviews each command and blocks the ones it rejects. Without auto mode, commands outside a built-in read-only set ask first (permission modes).
Research during planning often goes to the built-in Plan subagent, which has read-only tools, so the main session stays read-only while it searches. More on that in Claude Code subagents.
What happens when the plan is ready?
Claude shows the plan and asks how to continue:
| Option | What it does |
|---|---|
| Yes, and use auto mode | Approves the plan and starts building in auto mode. When auto mode is not available it reads "Yes, auto-accept edits" |
| Yes, manually approve edits | Approves the plan, and you review each edit as it comes |
| No, keep planning | Stays in plan mode. Tell Claude what to change |
Approving leaves plan mode and switches to the mode the option names. With the showClearContextOnPlanAccept setting on, an extra first option approves the plan and clears the planning conversation, so the build starts with a clean context. Press Ctrl+G to open the plan in your text editor and change it before Claude starts. Plan files are kept in ~/.claude/plans/, and the plansDirectory setting moves them (permission modes).
When is plan mode worth it?
| Task | Plan first? |
|---|---|
| A change across several files, or a new feature | Yes |
| Code you do not know yet | Yes, and ask questions before the plan |
| A database migration or anything hard to undo | Yes, and choose manual approval of edits |
| A one-line fix or a typo | No, the plan costs more than the fix |
| A task you could describe in one sentence with the exact file | Usually not |
Read the plan the way you would read a pull request description. Check the list of files, the order of steps and how Claude will know it worked. A plan with no test or build step at the end is the one to send back.
A plan mode session, step by step
- Commit or stash your current work, so the build step starts from a clean tree.
- Press Shift+Tab until the status bar shows plan mode on.
- Describe the goal and the limits: what must not change, which tests must pass.
- Answer Claude's questions. Ask it to name the files it will touch.
- Press Ctrl+G if you want to edit the plan text yourself.
- Approve with manual edit review the first few times, and with auto mode once you trust the pattern.
- When it is done, run the tests yourself and read the diff before you commit.
Plan how to add password reset to this app. Do not write code yet. List the files you will change or create, the order of the steps, how the reset token is stored and expires, and which tests you will add. Ask me anything you need to decide first.For the habits around planning, such as small tasks and a commit before each one, see Claude Code best practices. Cursor has its own Plan Mode on the same Shift+Tab key; the two tools are compared in Cursor vs Claude Code.
Frequently asked questions
How do I turn on plan mode in Claude Code?
Press Shift+Tab until the status bar shows plan mode on. You can also start with claude --permission-mode plan, or type /plan before a single prompt.
Can Claude edit files in plan mode?
No. It can read files and run exploring commands, but edits to your source are blocked until you approve the plan.
How do I make plan mode the default?
Set permissions.defaultMode to "plan" in .claude/settings.json. In VS Code, set claudeCode.initialPermissionMode to plan in your user settings instead.
How do I edit the plan before Claude starts?
Press Ctrl+G to open it in your default text editor, or choose "No, keep planning" and tell Claude what to change.
How do I leave plan mode without approving?
Press Shift+Tab again to move to the next mode.
Next guideCursor vs Claude Code →