Claude Code plan mode: how to make Claude plan before it edits

What is plan mode in Claude Code?

Plan mode is a Claude Code permission mode where Claude researches your code and proposes a plan without changing any files. It reads files, can run shell commands to explore, and writes a step-by-step plan, but your source stays untouched until you approve that plan. You turn it on with Shift+Tab, the /plan command, or claude --permission-mode plan.

The point is to separate thinking from doing. The official best practices put it plainly: letting Claude jump straight to coding "can produce code that solves the wrong problem." Plan mode gives you a checkpoint where you can read Claude's approach, push back, and fix misunderstandings while they are still cheap, before a single line is written.

Plan mode is one of six permission modes. The others control how much Claude can do without asking; plan mode is the only one built around not editing at all. The cheat sheet has a table of all six.

How do you turn on plan mode?

There are four ways, depending on whether you want it for one prompt, one session, or by default.

Shift+Tab cycles through the permission modes. According to the permission modes docs, if you start in auto mode the first press switches to Manual (default), and the cycle then runs Manual, accept edits, plan. Optional modes such as auto and bypass permissions slot in after plan. Watch the status bar under the prompt to see where you are.

To start a session in plan mode from your shell:

claude --permission-mode plan

To make plan mode the default for everyone who opens the project in a terminal, commit this to .claude/settings.json:

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

The VS Code extension does not read project settings for its starting mode. There, set claudeCode.initialPermissionMode to plan in your VS Code user settings instead. In the desktop app, picking Plan from the mode selector applies to the current session only.

What can Claude do in plan mode?

In plan mode Claude can read files, search the codebase, and write a plan. It does not edit your source. The plan itself is saved as a file, by default under ~/.claude/plans; the plansDirectory setting moves it somewhere else, such as a ./plans folder in your repo.

Shell commands are where it gets more nuanced. The official docs list three cases, and the first that matches applies:

1. Interactive terminal session with bypass permissions available. Planning commands run with no classifier and no prompt. In this one setup, Claude Code also does not enforce plan mode's edit block: Claude is still told to plan without editing, but an edit it attempts would run.
2. Auto mode available and useAutoModeDuringPlan on (the default). The auto mode classifier reviews each shell command instead of asking you. Approved commands run; rejected ones are blocked.
3. Auto mode not available, or useAutoModeDuringPlan set to false. Any command outside the built-in read-only set asks for your approval.

So if plan mode keeps prompting you for commands like npm test, you are in case 3. If you would rather approve every command yourself during planning, set "useAutoModeDuringPlan": false in your user or local settings. A repository's shared settings cannot turn it off for you.

Plan mode keeps its blocks wherever there is no interactive terminal: claude -p runs, Agent SDK sessions, and the VS Code chat panel.

The Plan subagent

When Claude needs to understand a large codebase during planning, it can hand the research to a built-in Plan subagent. The subagents docs describe it as "a research agent used during plan mode to gather context before presenting a plan." Its exploration happens in a separate context window, so your main conversation stays focused on the plan rather than filling up with file dumps. Our subagents guide explains how that delegation works.

How do you approve, edit or reject a plan?

When the plan is ready, Claude shows it and asks how to proceed. The options are:

• Yes, and use auto mode. Approve and let Claude implement in auto mode. If auto mode is not available to you, this reads Yes, auto-accept edits instead.
• Yes, manually approve edits. Approve, but review each edit as Claude makes it.
• No, keep planning. Stay in plan mode and tell Claude what to change.

Approving exits plan mode and switches the session to whichever mode that option names, and Claude starts working. To plan again later, cycle back with Shift+Tab or start your next prompt with /plan. Accepting a plan also gives the session a generated title based on the plan, unless you already named it.

To change the plan yourself, press Ctrl+G. The plan opens in your default text editor; edit it, save, and Claude works from your version.

Planning can use a lot of context. If you turn on showClearContextOnPlanAccept, the approval menu gains a first option, Yes, clear context and ..., that approves the plan, clears the conversation, and starts implementing from the plan alone. That is useful after a long research phase.

{
  "showClearContextOnPlanAccept": true
}

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

When should you use plan mode?

Use plan mode when you are unsure of the approach, when the change touches several files, or when you do not know the code well. The official guidance offers a simple test: "If you could describe the diff in one sentence, skip the plan."

Plan mode adds a round trip, so it is overhead on small, obvious changes. Typos, a new log line, a variable rename: ask for those directly. Good candidates for planning:

• A feature that crosses layers, such as a new API route plus UI plus tests
• A refactor or migration across many files
• A bug whose cause you do not know yet
• Your first task in an unfamiliar repo
• Anything touching billing, auth or data you cannot easily restore

Some teams write this into their project instructions. The official memory docs even use "Use plan mode for changes under src/billing/" as an example line for a CLAUDE.md. See the CLAUDE.md guide for how to write rules like that.

A planning workflow that works

The official best practices recommend four phases: explore, plan, implement, commit. The first two happen in plan mode.

1. Explore. Ask Claude to read the relevant code and explain it back. Nothing changes yet.

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

2. Plan. Ask for a concrete plan with the files that will change.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

Read the plan carefully. Press Ctrl+G to edit it, or choose No, keep planning and correct it in chat.

3. Implement. Approve the plan, or press Shift+Tab to leave plan mode, and let Claude build against it.

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

4. Commit. Ask Claude to commit with a clear message and open a pull request.

Prompts that produce better plans

A plan is only as good as the brief behind it. A few habits help:

• Name the goal and the constraint. "Add rate limiting to the login route without adding a new dependency" gives Claude a boundary to plan within.
• Ask for the file list. "List every file you expect to change and why" makes gaps obvious.
• Ask for risks and open questions. "What could break, and what do you need me to decide?" surfaces the choices you should make, not Claude.
• Ask for a test plan. "How will we verify this works?" pushes Claude to plan its own checks. The official best practices put giving Claude a check it can run at the top of their list.
• Point at examples. "Follow the pattern in src/api/users.ts" keeps the plan consistent with your codebase.

/plan add CSV export to the reports page. list every file you will change
and why, call out risks and anything you need me to decide, and describe
how we will test it. follow the existing pattern in src/api/users.ts.

If you write a planning brief like that more than twice, save it. Kipt keeps prompts like this in a private GitHub repo you own, so a good planning template is one Cmd+K search away in any project.

Plan mode vs ultrathink and effort

Plan mode decides what Claude may do. Reasoning depth is a separate dial.

• ultrathink. The model configuration docs say to include ultrathink anywhere in a prompt to request deeper reasoning on that turn without changing your session's effort setting. Other phrases such as "think hard" or "think more" are passed through as ordinary text, not recognized keywords.
• Effort. /effort sets how much reasoning Claude applies across the session, from low to max. You can also pass --effort at launch.
• Extended thinking toggle. Option+T on macOS or Alt+T elsewhere toggles extended thinking, but it has no effect on models that always think, including Opus 5.5 and Sonnet 5.5.

They combine well: plan mode plus ultrathink on a hard design question gives you a careful plan you can review before anything changes.

Plan on Opus, build on Sonnet with opusplan

The opusplan model setting uses Opus while you are in plan mode and switches to Sonnet for execution. That pairs a stronger model for design decisions with a faster one for writing code.

claude --model opusplan

You can also switch inside a session with /model opusplan.

Common plan mode problems

Claude keeps asking to run commands while planning. Auto mode is not available in your session, or useAutoModeDuringPlan is off, so commands outside the read-only set prompt. Approve them, or check your /config setting Use auto mode during plan.

Claude edited a file while in plan mode. Check whether you started the session with --dangerously-skip-permissions or --allow-dangerously-skip-permissions. In an interactive terminal with bypass permissions available, plan mode's blocks are not enforced.

The plan ran out of context. Turn on showClearContextOnPlanAccept so you can approve and start fresh from the plan, or ask Claude to keep research in subagents.

Plan mode does not stick in VS Code. The extension ignores the project's defaultMode. Set claudeCode.initialPermissionMode in your VS Code user settings.