Claude Code Plan Mode: How It Works, How to Use It, and When to Skip It

Claude Code Plan Mode: How It Works, How to Use It, and When to Skip It

The most expensive Claude Code mistake I know is not a bad edit. It is a confident edit. You ask for a refactor, the agent picks an approach in about four seconds, and twenty minutes later you are reading a diff across twelve files that solves a slightly different problem than the one you had. Nothing is broken. It is just wrong, and the cost of finding that out is the whole diff.

Plan mode is the fix for that, and it costs almost nothing. Claude reads your code, writes down what it intends to do, and waits. You read the plan, change it if it is off, and only then does anything get edited. I wrote a short section on it in the beginner guide and a one-line entry in the commands cheat sheet, but it deserves its own page, because most of what makes it useful is in the details.

This guide covers how to turn it on, what Claude can and cannot do inside it, the approval menu, how to edit a plan, the settings that change its behavior, and the cases where I skip it. I checked everything against the official permission modes documentation on October 27, 2026. Claude Code changes often, so treat the docs as the source of truth if something here has drifted.

What Claude Code Plan Mode Is

Claude Code plan mode is a permission mode where Claude researches your codebase and proposes changes without making them. It can read files, run shell commands to explore, and write a plan. It cannot edit your source files until you approve the plan.

That is the whole idea. The mode changes one thing: whether Claude is allowed to change your code. Everything else about the session stays the same, including your CLAUDE.md, your tools and your conversation history.

It helps to think of it as two phases. In the first, Claude gathers context and reasons. In the second, after you approve, it executes with the permissions of whichever mode you picked on the approval screen. The plan is the handoff between the two, and it is also the thing you get to review, which is the point.

How to Turn On Plan Mode in Claude Code

There are several ways in, and which one you use depends on whether you want it once, for a session, or by default.

A few notes on those.

Shift+Tab cycles modes. In default mode the cycle runs default, then acceptEdits, then plan, so you usually press it twice. If you have auto mode available, the first press from auto drops you to default first. Watch the status bar instead of counting. Press Shift+Tab again to leave plan mode without approving anything. On Windows, if Shift+Tab does not cycle because your Node or Bun runtime does not enable VT input mode, use Alt+M.

/plan is the one I use most. Typing /plan followed by a description puts Claude in plan mode and gives it the task in one move. The slash command has to be at the very start of the message, like every slash command. The full list of what else lives at that level is in the commands cheat sheet.

To make plan mode the default for a project, put this in .claude/settings.json:

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

VS Code is the exception. VS Code sessions do not read the project setting for the starting mode. Set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.

Do I recommend plan mode as a default? Not for most people. Every session starts with a plan step, including the ones where you just want a typo fixed. I would use it as a default in one case: a repo you are new to, where every change should start with Claude proving it understood the code.

What Claude Can and Cannot Do in Plan Mode

Inside plan mode, Claude can:

• Read files and search the codebase.
• Run shell commands to explore, such as git log, ls or a test listing.
• Ask you clarifying questions.
• Write the plan itself.

It cannot edit your source files until you approve the plan. That is the guarantee, with one important exception covered in the section on limits below.

Shell commands are where it gets less obvious, because "run commands to explore" still needs a rule for which commands count. The docs describe three cases, and the first one that matches applies:

1. Interactive terminal with bypass permissions available. Neither the classifier nor a prompt applies to planning commands. Claude is told not to edit, but anything it attempts runs. Explicit ask rules and critical-path rm removals still prompt.
2. Auto mode available and useAutoModeDuringPlan on (the default). The classifier reviews shell commands instead of prompting you. Approved ones run, rejected ones are blocked.
3. Auto mode not available, or useAutoModeDuringPlan off. Commands outside the built-in read-only set prompt for approval.

In practice, on a normal setup, you will see Claude run read-only commands freely and ask before anything that could change state. That is what you want from a planning phase.

The Plan Approval Menu

When the plan is ready, Claude presents it and asks how to proceed. The options you will see:

• Yes, and use auto mode. Approves the plan and starts auto mode, where a classifier approves routine actions. If auto mode is not available to your session, this reads Yes, auto-accept edits instead.
• Yes, manually approve edits. Approves the plan, but you review each edit one by one.
• No, keep planning. Stays in plan mode so you can tell Claude what to change.

If your session started with bypass permissions enabled, the first option instead reads Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session. Read that label before you press Enter. It is the same switch as running with --dangerously-skip-permissions.

There is also an optional option that clears the planning context. When showClearContextOnPlanAccept is enabled, a new first option appears that approves the plan and clears the conversation used to build it. That sounds odd until you have done a long planning session: the research, the dead ends and the back-and-forth all sit in the context window, and none of them help the implementation. Starting clean with just the approved plan can leave the execution phase with more room to work and fewer old assumptions to trip over. If you often plan for a long time, turn it on.

Approving exits plan mode and moves you to whatever mode the option describes. To plan again, cycle back with Shift+Tab or prefix a prompt with /plan. Accepting a plan also gives the session a title generated from the plan, unless you already named it.

Edit the Plan with Ctrl+G

This is the feature most people never find. Press Ctrl+G while a plan is on screen and Claude opens it in your default text editor. Change it, save, close, and Claude proceeds with your version.

Why bother, when you could just reply and ask for changes? Because some corrections are faster to make than to describe. Deleting a step you do not want is one keystroke. Reordering two steps is a cut and paste. Adding a constraint like "do not touch the public API" is one line. Telling the model to do any of that and waiting for it to rewrite the plan is slower and risks it rewording things you did not ask it to change.

Plan files for the current session live in ~/.claude/plans/, or in the directory set by the plansDirectory setting. Writes to ~/.claude/plans/ are exempt from the protected .claude directory rule, which is why Claude can save a plan there even in modes that guard that folder. If you want plans in the repo so teammates can read them, point plansDirectory at a project folder.

A Plan Mode Workflow That Works

Here is the loop I use, with a real-shaped example. The task: add rate limiting to an Express API that already has auth middleware.

1. Start with the goal and the constraints, not the solution.

/plan Add per-user rate limiting to the API. Use the existing Redis client.
Do not change the auth middleware's public behavior. Show me which files
you would touch before touching any.

Giving Claude the constraints up front is what keeps the plan from drifting. "Use the existing Redis client" saves me from a plan that adds a second dependency.

2. Let it read, then read the plan critically.

A useful plan names files, in order, and says why. A weak one says "update the relevant middleware." Here is the shape of a good one:

1. Add src/middleware/rateLimit.ts using the client from src/lib/redis.ts
2. Key limits by req.user.id, fall back to IP for unauthenticated routes
3. Register it after auth in src/app.ts so req.user exists
4. Add tests in src/middleware/rateLimit.test.ts (limit hit, reset, no user)
5. Document the new env vars in README.md

3. Push back before approving.

Questions I ask at this step: what did you not read? What is the riskiest step? What happens to the unauthenticated routes? A plan is cheap to question. Code is not. If an answer surprises me, I say "No, keep planning" and give the correction.

4. Edit with Ctrl+G when the fix is small.

If step 5 is out of scope, I delete it in the editor rather than debating it.

5. Approve with the mode that matches the risk.

For a change this size, I pick manual approval for the first run and auto mode once I trust the plan. The plan has already done the thinking, so the edits become mostly mechanical.

That whole loop adds a few minutes. The first time it catches a wrong assumption about the codebase, it pays for a month of them.

When to Use Plan Mode and When to Skip It

My rule: use plan mode when a wrong first step is expensive.

Use it for:

• Changes across more than a couple of files. Refactors, renames that cross module boundaries, anything with a migration.
• Code you do not know. A repo you just cloned, or a part of your own app you have not touched in a year. The plan shows you whether Claude understood the structure before it changed anything.
• Irreversible or expensive changes. Database migrations, public API changes, dependency upgrades with breaking changes.
• Work you will hand off or review. A written plan is an easy thing to put in a pull request description.
• When you are not sure what you want. Asking for a plan is a cheap way to see options.

Skip it for:

• One-line fixes. A typo, a changed constant, a renamed variable. The plan would be longer than the diff.
• Tasks with an obvious single path. "Add this field to this type" does not need a review step.
• Throwaway experiments. If you are going to delete it in ten minutes, do not spend three on a plan.
• Quick questions. Reading code and answering does not need a mode.

One more mistake worth naming: planning forever. Three rounds of plan revisions on a small task is usually a sign the task needs to be split, not that the plan needs another pass. Approve a smaller plan and do the next piece afterward.

Plan Mode Is Not a Sandbox

This is the caveat people miss, and it is a real one. Plan mode blocks edits by telling Claude not to make them and denying the tools, but in an interactive terminal where bypass permissions is available, those blocks are not enforced. Claude is still told to plan without editing. If it attempts an edit or a shell command anyway, it runs without a prompt.

So the safe reading is: plan mode is a workflow, and a good one, but it is not a security boundary. If the point is to guarantee nothing changes, do not start the session with --dangerously-skip-permissions. And if you need real limits on what an agent can touch, that is a permissions and sandbox question, which I cover in the least-privilege guide for coding agents.

Plan mode keeps its blocks everywhere that runs without an interactive terminal: claude -p runs, Agent SDK sessions and the VS Code chat panel.

Plan Mode Settings Worth Knowing

I would change two of those. Turn on showClearContextOnPlanAccept if your planning sessions run long, and set plansDirectory to a project folder if you want plans in version control. Leave the rest alone until you have a reason.

Using Plan Mode in Headless Runs

The --permission-mode flag works with -p, so this is the headless form:

claude -p --permission-mode plan "Plan how to migrate the users table to UUID primary keys"

Because plan mode keeps its blocks in non-interactive runs, nothing gets edited, which makes this a decent way to run a read-only analysis in a script or CI job. The docs do not describe an interactive approval step for -p runs, so treat it as a one-shot "give me the plan" call rather than a plan-then-execute flow.

Plan Mode with opusplan and Subagents

Two features pair well with plan mode.

opusplan is a model alias that uses Opus while you are in plan mode and switches to Sonnet for the edits. It matches how the work splits: planning is the part where a stronger model pays off, and executing an approved plan is mostly mechanical. Pick it with /model. My Claude Code vs Codex comparison covers the model lineup and what each plan includes.

Subagents help when the research phase is large. Claude Code's built-in Plan subagent is read-only, with Write and Edit denied, and it is used for research during plan mode. Custom subagents can do the same job with their own prompts and tools, and they keep the exploration out of your main context window. The subagents guide shows how to write one.

Common Plan Mode Problems

Shift+Tab skips plan mode or does nothing. The cycle depends on which modes are available to you, so count by the status bar, not by presses. On Windows, use Alt+M if Shift+Tab is not recognized.

The plan is vague. "Update the relevant files" is a signal that Claude did not read enough. Ask: "Which files did you read? Name the exact files you will change and why." Or point it at the starting files with @.

It plans something huge. Ask for a smaller first slice: "Plan only the data layer. We will do the API after." Splitting the work gives you plans you can actually verify.

It edited something anyway. Check whether bypass permissions was on. In that setup plan mode is advisory, as described above. Use Esc twice or /rewind to undo, and start the next session without the bypass flag.

The execution drifts from the plan. Long planning sessions leave a lot of context. Turn on the clear-context option so the execution phase starts from the approved plan alone, and consider running /compact mid-task if it still drifts.

Plan Mode vs Just Asking for a Plan

You can type "write a plan first, do not edit anything" in the default mode, and sometimes that is enough. The difference is enforcement and workflow. In plan mode the edit tools are denied, there is a defined approval step, and you get the menu and Ctrl+G. In default mode with a polite request, Claude can forget the instruction two messages later, or interpret "plan" loosely and start changing files. If the cost of an unreviewed edit is real, use the mode. If you only want an outline to think with, asking is fine.

Plan mode also pairs well with the other habits in the 32,784-line workflow post: a written plan, small steps and a review between each. The plan is the cheapest checkpoint in the whole loop.

Frequently Asked

What is plan mode in Claude Code? A permission mode where Claude reads your code and writes a plan but does not edit source files until you approve it.

How do I enter plan mode in Claude Code? Press Shift+Tab until the status bar shows plan mode, type /plan with an optional description, start with claude --permission-mode plan, or set permissions.defaultMode to "plan" in settings.

How do I exit plan mode? Approve the plan from the menu, or press Shift+Tab again to leave without approving. To plan again later, cycle back or prefix a prompt with /plan.

Can Claude edit files in plan mode? Not source files, until you approve the plan. The exception is an interactive terminal session with bypass permissions available, where the block is not enforced.

Can I edit the plan before approving it? Yes. Press Ctrl+G to open it in your default text editor, edit it and save.

Where are Claude Code plans saved? In ~/.claude/plans/ by default, or the folder set by the plansDirectory setting.

Does plan mode cost more tokens? It adds a planning pass, so a task uses more tokens up front. It often saves them overall by avoiding a wrong implementation that has to be rewritten. If usage is your worry, opusplan and a clear-context approval help.

Should I use plan mode for every task? No. Use it when a wrong first step is expensive, and skip it for small, obvious changes.

Does plan mode work in headless mode? Yes, with claude -p --permission-mode plan. Nothing is edited, and the run is a read-only analysis.

Source: Claude Code permission modes, checked October 27, 2026.