Claude Code Plan Mode: How to Use It and When

Claude Code plan mode makes Claude research and propose a change before it touches your code. Claude reads files, runs commands to explore, and writes a plan. Your source files stay unedited until you approve that plan.

Here is the short version:

• Enter it with Shift+Tab until the status bar shows ⏸ plan mode on, type /plan, or launch with claude --permission-mode plan.
• Make it the default by setting defaultMode to plan in .claude/settings.json.
• Approve, edit or reject the plan when Claude presents it. Ctrl+G opens it in your text editor.
• Pair it with opusplan if you want Opus for planning and Sonnet for the edits.

Everything below comes from Anthropic's permission modes documentation and the pages it links to, as of October 2026.

What Claude Code plan mode actually does

Plan mode is one of the permission modes in Claude Code. The others decide how much Claude may do without asking. Plan mode is different. It tells Claude to research and propose changes without making them.

In practice, a planning session looks like this:

1. You describe the task.
2. Claude reads the relevant files and runs shell commands to look around.
3. Claude writes a plan: which files change, in what order, and why.
4. You approve it, edit it, or send Claude back to keep planning.
5. Only after approval does Claude start editing.

The plan itself is a file. By default Claude Code stores plan files in ~/.claude/plans. The plansDirectory setting in the settings reference moves them somewhere relative to your project root, such as ./plans, if you want plans to sit next to the code.

If you came here from our guide to Claude Code permissions, that post covers all six modes, allow and deny rules, and which settings file wins. This one stays on plan mode: how to get in, what happens inside, and how to get out with a plan you trust.

How to enter plan mode in Claude Code

There are four ways in, depending on whether you're mid-session, starting fresh, or setting a project-wide habit.

Shift+Tab cycling

Shift+Tab cycles through permission modes in the CLI. If your session started in auto mode, the first press switches to Manual (default). From there the cycle runs default, then acceptEdits, then plan. Optional modes such as bypassPermissions and auto slot in after plan when they're available to you.

So from a fresh auto-mode session, plan mode is usually three presses away. Watch the status bar rather than counting. On Windows, the docs list Alt+M as the fallback when the runtime doesn't enable VT input mode.

To leave plan mode without approving anything, press Shift+Tab again.

The /plan command

The commands reference documents /plan [description]. On its own it switches you into plan mode. With a description, it enters plan mode and starts on that task right away:

/plan migrate the session store from cookies to Redis

Starting a session in plan mode

claude --permission-mode plan

The same flag works with -p for non-interactive runs. Plan mode keeps its blocks there too, which makes it a safe way to ask for an analysis in a script. Our post on Claude Code headless mode covers the rest of -p.

Set plan mode as the default with defaultMode

To make every terminal session in a project start in plan mode, add this to the project's .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Put the same block in ~/.claude/settings.json to apply it to every project on your machine. When more than one file sets defaultMode, settings precedence decides, so a project value outranks your user file.

One exception: the VS Code extension doesn't read project settings for its starting mode. There, set claudeCode.initialPermissionMode to plan in your VS Code user settings. In the extension's mode indicator, picking Plan applies to that conversation only, while a pick of Manual, Edit automatically or Auto carries over to new conversations.

What Claude can and can't do in plan mode

The core rule is simple. Claude can read and explore. It can't edit your source until you approve a plan. The details sit in how shell commands are handled. The docs describe three cases, and the first one that matches your session applies.

That first row matters. If you launched with --dangerously-skip-permissions or --allow-dangerously-skip-permissions, a file edit Claude attempts during planning runs without a prompt. Explicit ask rules and recognized rm and rmdir removals on critical paths still prompt. Plan mode is an instruction plus a guard, and in that setup the guard is off.

If you'd rather approve every non-read-only command yourself while planning, set useAutoModeDuringPlan to false. It appears in /config as Use auto mode during plan.

Outside an interactive terminal, the blocks always hold. That includes -p runs, Agent SDK sessions, and the VS Code extension's chat panel.

Claude can also move between modes on its own. The tools reference lists an EnterPlanMode tool, which switches to plan mode to design an approach before coding, and an ExitPlanMode tool, which presents a plan for approval. Exiting is the step that needs your permission.

Approving or editing a plan

When the plan is ready, Claude presents it and asks how to proceed. You get three choices:

Approving exits plan mode and switches the session to the mode that option names. To plan again later, cycle back with Shift+Tab or prefix your next prompt with /plan. The approval prompt also never times out on idle, so a plan can wait while you read it.

Edit the plan directly with Ctrl+G

Press Ctrl+G and the proposed plan opens in your default text editor. Delete a step, reorder the migration, add the missing test, then save and let Claude proceed from your version.

This is often faster than "No, keep planning" for small corrections. Use the chat route when the approach itself is wrong. Use Ctrl+G when the approach is right and the details aren't.

Clear context on approval

Planning can eat a lot of context, since Claude reads many files to write a good plan. The showClearContextOnPlanAccept setting adds a first option to the approval menu, Yes, clear context and …, which approves the plan, clears the conversation, and starts implementing from the plan alone. The label also shows how much of your context the planning used.

{
  "showClearContextOnPlanAccept": true
}

It's off by default. Turn it on if your sessions tend to run long after a big planning pass. Accepting a plan also gives the session a generated title based on the plan, unless you've already named it.

The opusplan model alias

Planning and implementing reward different things. Planning is reasoning-heavy, while the edits that follow are mostly execution. The opusplan alias in the model configuration docs splits the work:

• In plan mode, it uses opus for complex reasoning and architecture decisions.
• In execution mode, it automatically switches to sonnet for code generation and implementation.

Set it mid-session with /model opusplan, or at launch with claude --model opusplan. For a 1M context window in both phases where the models don't already run with it by default, the docs give opusplan[1m].

If your organization restricts models with availableModels, opusplan uses the newest permitted Opus for planning and stays on Sonnet only when every Opus is excluded. For a broader look at which model suits which coding job, see which Claude model is best for coding.

When to use Claude Code planning, and when to skip it

Anthropic's best practices guide recommends a four-phase loop: explore, plan, implement, commit. Plan mode covers the first two. You ask Claude to read the relevant code, then ask for a detailed plan, then approve and let it build against that plan.

The same guide is just as clear that plan mode adds overhead. Its rule of thumb: if you could describe the diff in one sentence, skip the plan.

A good planning prompt names the area and the goal. The docs' own example reads the auth code first, then asks: "I want to add Google OAuth. What files need to change? What's the session flow? Create a plan." That is concrete enough for Claude to read the right files and specific enough for you to judge the result.

And if a plan you approved still goes sideways during implementation, you're not stuck with it. Rewind restores the code and the conversation to an earlier point.

Planning before you touch anything

Plan mode is Claude Code's way of making you look before it leaps, and for developers working in a real repo it's worth the extra step. If you're not running a terminal agent at all, Taku is a different shape: an AI-native desktop workspace where you mirror an AI setup someone has already got working, run it, and keep it. Taku is in Beta, and the Mac app is available now.

FAQ

How do I turn on plan mode in Claude Code?

Press Shift+Tab until the status bar shows ⏸ plan mode on, type /plan, or start with claude --permission-mode plan. To make it the default for a project, set defaultMode to plan in .claude/settings.json.

Is there a /plan command in Claude Code?

Yes. /plan enters plan mode from the prompt, and /plan followed by a description enters plan mode and starts on that task, for example /plan fix the auth bug.

Can Claude edit files in plan mode?

Not until you approve the plan. The one exception is an interactive terminal session started with bypass permissions available, where plan mode's blocks aren't enforced.

Can Claude run commands while planning?

Yes, to explore. With auto mode available, a classifier reviews each command. Without it, anything outside the built-in read-only set asks you first.

How do I edit a 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.

What is opusplan in Claude Code?

A model alias that uses Opus while you're in plan mode and switches to Sonnet for execution. Set it with /model opusplan.

How do I exit plan mode without approving?

Press Shift+Tab again to cycle to the next mode.

Where does Claude Code save plans?

In ~/.claude/plans by default. Change it with the plansDirectory setting, using a path relative to your project root.