Why plan mode
Jumping straight into complex work risks:
- Going far in the wrong direction before you can stop it
- Hiding the change scope from you until after the fact
- Magnifying losses when an assumption is wrong
Plan mode is the gate before any code change — it shows you the plan, you approve, then it runs. Slightly slower upfront, much higher success rate on complex work.
Enter and exit
| Method | What it does |
|---|---|
| Shift+Tab | Cycles permission modes: default → acceptEdits → plan. If bypass permissions or auto mode is available, they follow plan in the cycle. |
/plan prefix | Prefix a single prompt with /plan to enter plan mode. Add a description, like /plan fix the auth bug, to start planning right away. |
claude --permission-mode plan | Starts the session in plan mode. |
permissions.defaultMode: "plan" | In .claude/settings.json, makes plan mode the default for the project’s terminal sessions. In the VS Code extension, set claudeCode.initialPermissionMode to plan in your user settings instead. |
While plan mode is on, the status bar shows ⏸ plan mode on. Press Shift+Tab again to leave plan mode without approving a plan.
What a good plan contains
Claude’s plan typically includes:
- Context — why the change is needed
- Files to modify — exact paths
- What changes per file — function or section level
- Assumptions — what state or environment is assumed
- Verification — build, tests, manual checks
If a section is empty, ask Claude to fill it. If an assumption is wrong, correct it and ask for a revised plan.
Approving the plan
When the plan is ready, Claude presents it and asks how to proceed:
| Option | What it does |
|---|---|
| Yes, and use auto mode | Approve and start in auto mode. If auto mode isn’t available to your session, this option reads Yes, auto-accept edits. |
| Yes, manually approve edits | Approve and review each edit individually. |
| No, keep planning | Stay in plan mode and tell Claude what to change. |
Approving a plan exits plan mode and switches the session to the permission mode the option describes. Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds.
When to use it
| Good fit | Skip it |
|---|---|
| New feature (3+ files) | Single typo fix |
| Refactor | Single-file rename |
| DB migration | Adding a console.log |
| Dependency change | Comment edits |
| API signature change | Obvious bug fixed in seconds |
What to review
- Missing files — affected files Claude didn’t catch
- Wrong assumptions — “assumes X exists” — does it?
- Irreversibility cost — migrations, deletions, data changes
- Test plan — how the change will be verified after the fact
Mid-execution adjustments
When execution needs to deviate from the plan, cycle back to plan mode with Shift+Tab, or prefix your next prompt with /plan, get a revised plan, then resume.
Pairs with
- CLAUDE.md — “Use plan mode for complex changes” as a rule encourages Claude to suggest it.
- Superpowers — the
superpowers:writing-plansandsuperpowers:executing-plansskills save plans as files for larger work. (The legacy/write-planand/execute-plancommands were removed in Superpowers v5.1.0.) - claude-mem — preserve plans and progress across sessions.
Common misconceptions
- “Plan mode means no edits at all” — mostly. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source until you approve. When auto mode is available, the classifier reviews shell commands instead of prompting you. The exception: in interactive terminal sessions with bypass permissions available, plan mode won’t ask before most edits or commands.
- “Approval guarantees execution exactly as planned” — usually yes, but Claude stops if it hits an issue.
- “Plan mode is always better” — for trivial work it’s overhead. Use it when impact is broad.
Next steps
- Superpowers — extend planning and execution with skills
- claude-mem — preserve plans and progress across sessions
- Writing a Great CLAUDE.md — encode plan-mode rules in CLAUDE.md
- Permission modes docs — current plan mode behavior and settings