Ask Claude Code for a big change and it starts editing straight away. Most of the time that's what you want. Sometimes, though, you'd rather see the approach first: which files it will touch, in what order, and what it has assumed about your code. Plan mode makes Claude stop and show you that before it changes anything.
What plan mode does
Plan mode is one of Claude Code's permission modes. In it, Claude reads files, runs shell commands to explore, and writes a plan, but it doesn't edit your source. When the plan is ready, Claude shows it to you and waits. Nothing changes on disk until you approve.
While it's on, the status bar under the prompt shows ⏸ plan mode on.
Shell commands during planning depend on your setup. If auto mode is available to your session, a classifier reviews each command and runs the ones it approves without asking you. That's controlled by the useAutoModeDuringPlan setting, which is on by default. Without auto mode, any command outside Claude Code's built-in read-only set asks for your approval.
Turn it on
There are four ways in, depending on whether you want it for one prompt, one session or every session.
| You want | Do this |
|---|---|
| Plan mode now, mid-session | Press Shift+Tab until the status bar shows ⏸ plan mode on |
| Plan mode for one task | Start the prompt with /plan, for example /plan fix the auth bug |
| A whole session in plan mode | Start with claude --permission-mode plan |
| Every session in one project | Set defaultMode to plan in the project's .claude/settings.json |
Shift+Tab cycles through the modes in a fixed order: Manual, accept edits, plan, and then any optional modes you have, such as auto. If your session starts in auto mode, the first press takes you to Manual, so you'll press it three times to reach plan. Press it again to leave plan mode without approving anything.
For the project default, the setting goes under permissions:
{
"permissions": {
"defaultMode": "plan"
}
}Conversations started by the VS Code extension don't read the project file for their starting mode. There, set claudeCode.initialPermissionMode to plan in your VS Code user settings.
A planning session, start to finish
Start the session in plan mode and describe the change:
claude --permission-mode plan
> Add rate limiting to the public API. Read the existing middleware first, then propose where the limiter should go and which files change.Claude reads the middleware and the route setup, then comes back with a plan and asks how to proceed:
- Yes, and use auto mode: approve, and Claude starts working without routine prompts. If auto mode isn't available to you, this reads "Yes, auto-accept edits" instead.
- Yes, manually approve edits: approve, and review each edit as it comes.
- No, keep planning: stay in plan mode and tell Claude what to change.
Approving switches the session out of plan mode, so Claude starts editing. To plan the next change, cycle back with Shift+Tab or start the prompt with /plan again.
Before you approve, you can press Ctrl+G to open the plan in your text editor and change it yourself. If planning has filled a lot of your context, set showClearContextOnPlanAccept to true in your settings. The approval menu then gets a first option that approves the plan, clears the conversation and starts the work from the plan alone.
Claude Code saves each plan as a file, in ~/.claude/plans by default. To keep them with the project, set plansDirectory to a path inside it, such as "./plans".
When plan mode is worth it
Plan mode costs you a round trip: you read a plan before anything happens. That's worth paying when a wrong start is expensive.
- The change touches several files, and you want to agree the order before any of them move.
- You're new to the codebase and want to see what Claude found before it acts on it.
- There's more than one reasonable approach, and you have a preference Claude can't read from the code.
- The work is hard to undo, such as a migration or a change to shared configuration.
Skip it for small, obvious edits. If you could describe the whole diff in one sentence, a plan adds a step and tells you nothing new. A specific prompt is enough for those.
How I use it
My sessions don't start in plan mode. My ~/.claude/settings.json sets defaultMode to auto, and I switch to plan mode when a task calls for one. The trigger is written down in one of my rule files: for complex tasks that need deep reasoning, raise the effort level first, then turn on plan mode. Small edits never get there.
I also launch sessions with permission prompts bypassed and rely on hooks as the guardrail, so in my sessions plan mode depends on Claude following its instructions (see the next section). I accept that because the hooks block the commands I care about, such as deletes, whatever mode the session is in.
I let the plans pile up in the default folder rather than the project. ~/.claude/plans has 14 plan files in it as I write this, so I can go back to the reasoning behind an older change.
What plan mode won't do
If you start an interactive terminal session in a way that makes bypass permissions available, with --dangerously-skip-permissions, --allow-dangerously-skip-permissions or --permission-mode bypassPermissions, Claude Code doesn't enforce plan mode's blocks. Claude is still told to plan without editing, but if it tries an edit or a command, it runs without asking.
The blocks do hold where there's no interactive terminal: non-interactive runs with claude -p, Agent SDK sessions, and the VS Code extension's chat panel.
If you need edits blocked for certain, start the session without those flags.
Questions
Can Claude run commands in plan mode?
Yes. Claude runs commands to explore, such as listing files or reading git history. With auto mode available, a classifier approves or blocks each one. Without it, anything outside the read-only set asks you first.
How do I get out of plan mode without approving the plan?
Press Shift+Tab again. That moves you to the next mode in the cycle and leaves the plan unapproved. You can also choose "No, keep planning" at the approval prompt to stay in plan mode and revise it.
Should I make plan mode the default?
Only if most of your work in that project is large or risky. A default of plan mode means every task, including one-line fixes, goes through an approval step. For most people, switching in with Shift+Tab or /plan when a task needs it is the better habit.