Claude Code plan mode, past the two-keystroke version

Most people know plan mode as Shift+Tab twice. The mechanics matter more than the shortcut: what actually gets blocked, why commands still run while planning, why the approval prompt is a permission decision you make in a hurry, and how to keep a good plan from evaporating in the next compaction.

Plan mode is the highest-leverage habit in Claude Code and the one most people use least deliberately. The common version is: press Shift+Tab twice, read whatever comes back, hit the first option, and hope. That works often enough to feel fine, which is exactly why the parts underneath go unexamined.

We have argued elsewhere that planning before code is the single best habit and that a task should start from a file. This post is the mechanics: what plan mode blocks and what it does not, what the approval prompt actually decides, and how to stop a good plan from evaporating.

What plan mode is

Plan mode tells Claude to research and propose changes without making them. It reads files, explores, and writes a plan; your source stays untouched, and edits stay blocked until you approve. It is a permission mode, sitting in the same cycle as manual, accept-edits, and auto.

Three ways in, and most people know only the first:

# 1. During a session: cycle with Shift+Tab until the status bar shows plan mode.
# 2. For a single prompt, prefix it:
/plan refactor the token refresh path
# 3. For the whole session:
claude --permission-mode plan

The /plan prefix is the underused one. It gets you a planning turn without changing the session's mode, which fits the common case: you are working normally and one upcoming task deserves a design pass. Shift+Tab again leaves plan mode without approving anything.

To make it the default for a project, set defaultMode to plan in .claude/settings.json. Worth it on repos where a careless edit is expensive, and annoying everywhere else.

"No edits" does not mean "nothing runs"

The most common misreading: plan mode is not a read-only sandbox. Claude runs shell commands while planning, because research needs them. What governs those commands depends on your setup.

With auto mode available and useAutoModeDuringPlan on (the default), the classifier reviews each shell command during planning instead of you. Approved ones run, rejected ones are blocked. Without that, anything outside the built-in read-only set prompts you for approval.

So the accurate mental model is: file edits are blocked, commands are governed. A planning turn can still write to a scratch file through a shell command, hit the network, or run your test suite. That is usually what you want (a plan grounded in a real test run beats a plan grounded in a guess), but it is not the airtight read-only box people assume.

One important exception: in sessions where bypass permissions are available, plan mode's blocks are not enforced at all. Claude is still instructed to plan without editing, but an edit it attempts during planning goes through. If you run with --dangerously-skip-permissions, plan mode is a suggestion, not a guardrail.

The approval prompt is a permission decision

This is the part worth slowing down for. When the plan is ready, Claude asks how to proceed:

• Yes, and use auto mode: approve, and the session switches to auto mode, where the classifier reviews actions instead of you. When auto mode is unavailable this reads Yes, auto-accept edits. If the session was started with bypass permissions, it reads as switching to bypass permissions for the rest of the session.
• Yes, manually approve edits: approve, and review each edit yourself.
• No, keep planning: stay in plan mode and say what to change.

Approving a plan exits plan mode and moves the session into the mode that option names. The first option is therefore a one-keystroke change to your permission posture for the rest of the session, made at the exact moment your attention is on the plan's content rather than on permissions. It is the right choice for a well-scoped plan you just read carefully. It is the wrong reflex to build.

The rule that has served us: match the option to how carefully you read the plan. Skimmed it because it looked routine? Manual approval. Read it line by line and know what it touches? Auto is fine.

Keep the plan from evaporating

A plan lives in the conversation, and conversations get compacted. The good practices, in order of payoff:

Edit the plan before approving. Ctrl+G opens the proposed plan in your editor. Cutting a step or correcting an assumption there costs one line; discovering the same problem three tool calls into implementation costs a rollback.

Write it to a file for anything nontrivial. Ask for the plan in specs/ before you approve, then have the implementation reference the file. This is the same rule as skills: chat is steering, files are state. A file survives compaction, survives tomorrow, and can be handed to a different session or teammate.

Consider clearing the planning context. With showClearContextOnPlanAccept enabled, the approval list gains an option that approves the plan and clears the planning context. Research turns accumulate a lot of exploratory reading, and implementation rarely needs it. Clearing gives the implementation a clean window, which is the argument for writing the plan to a file first.

Two small niceties: accepting a plan gives the session a generated title based on it, which makes /resume lists readable, and the Plan research agent runs in its own context window (read-only, and it skips CLAUDE.md and git status), so heavy exploration does not crowd your main conversation.

When not to use it

Plan mode costs a turn, and turns are minutes. Skip it when the task is a one-line fix, when you already know exactly which file changes, or when you are iterating tightly on something you are watching anyway. Use it when the work spans files, when you are in unfamiliar code, when the cost of a wrong approach is a rollback rather than an edit, or when you want a written artifact for your future self.

There is also a rhythm cost worth naming. A planning turn is one of the longer waits in the day: the agent is reading dozens of files while you sit there. Reading a plan is real work, so give it your attention when it lands, but the four minutes before it lands are not work. That gap is the one Unwait fills with a flashcard, and it is the reason the product exists at all.

The short version

1. /plan for a single prompt, Shift+Tab for the session, defaultMode: plan for the project.
2. Edits are blocked; commands still run, reviewed by the classifier or by you.
3. Bypass permissions turns plan mode into an instruction rather than a block.
4. The approval prompt sets your permission mode for the rest of the session. Pick it deliberately.
5. Ctrl+G to edit the plan, then write anything nontrivial to a file before approving.

None of this makes the model smarter. It makes the cheapest correction point (before any code exists) the one you actually use, which over a week is worth more than any prompt trick.