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

> Claude Code plan mode makes Claude read your code and write a plan without editing any source until you approve it. Turn it on with Shift+Tab, /plan, claude --permission-mode plan, or permissions.defaultMode set to plan. Read the plan, push back, press Ctrl+G to edit it, then pick an approval option. Use it for changes that touch several files or an unfamiliar codebase, and skip it for one-line fixes. It is not a sandbox if bypass permissions is on.

Tags: ai, claude-code, claude, developer-tools, devtools
Published: 2026-10-27


# 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](/blog/how-to-use-claude-code-2026/) in the beginner guide and a one-line entry in the [commands cheat sheet](/blog/claude-code-commands-cheat-sheet-2026/), 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.

| Method | How | Scope |
| --- | --- | --- |
| Keyboard | `Shift+Tab` until the status bar shows `⏸ plan mode on` | Current session |
| Slash command | `/plan`, or `/plan fix the auth bug` to start straight away | One prompt |
| Startup flag | `claude --permission-mode plan` | The whole session |
| Settings default | `permissions.defaultMode` set to `"plan"` | Every terminal session in the project |
| Desktop app | Pick Plan in the mode selector | Current session |
| Web | Pick Plan in the dropdown for cloud sessions | Current session |

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](/blog/claude-code-commands-cheat-sheet-2026/).

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

```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.**

```text
/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:

```text
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](/blog/coding-agent-permissions-least-privilege-2026/).

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

| Setting | What it does | Default |
| --- | --- | --- |
| `permissions.defaultMode` | Set to `"plan"` to start every terminal session in plan mode | `default` |
| `useAutoModeDuringPlan` | Lets the auto mode classifier review shell commands during planning instead of prompting you | On |
| `showClearContextOnPlanAccept` | Adds an approve-and-clear-context option to the approval menu | Off |
| `plansDirectory` | Where plan files are saved | `~/.claude/plans/` |
| `claudeCode.initialPermissionMode` | VS Code user setting for the starting mode | n/a |

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:

```bash
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](/blog/claude-code-vs-codex-2026/) 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](/blog/claude-code-subagents-guide-2026/) 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](/blog/claude-code-workflow-32784-lines-2-days-2026/): 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](https://code.claude.com/docs/en/permission-modes), checked October 27, 2026.