# Claude Code plan mode: plan first, then let it build

URL: https://agentvera.dev/en/blog/claude-code-plan-mode/ · Published: 2026-10-25

Claude Code plan mode explained: how to turn it on with Shift+Tab or /plan, when to use it, plan-then-execute workflows, and pairing it with subagents and CLAUDE.md.

**In short:**

- In plan mode Claude Code reads files and explores the codebase, then writes a plan, but it edits nothing until you approve.
- Press Shift+Tab until the status bar shows plan mode, prefix a single prompt with /plan, or start with claude --permission-mode plan.
- Use it for changes that touch several files or that you can’t picture yet; skip it for one-line fixes.

Claude Code plan mode is the simplest way to stop an agent from charging off in the wrong direction. Instead of editing files straight away, Claude explores your code, asks what it needs to know and writes a plan. You read it, push back, and only when it looks right do you let it build. This guide covers how plan mode works today, how to turn it on, when it’s worth it and how to combine it with subagents and CLAUDE.md.

Everything here was checked against Anthropic’s [permission modes docs](https://code.claude.com/docs/en/permission-modes "Claude Code permission modes") and [common workflows](https://code.claude.com/docs/en/common-workflows "Claude Code common workflows") in October 2026.

## What is Claude Code plan mode?

Plan mode is one of Claude Code’s permission modes. In it, Claude can:

- read files and search the codebase,
- run shell commands to explore, such as listing files or reading git history,
- ask you clarifying questions,
- write a plan.

What it doesn’t do is edit your source code. The plan is a proposal, not a change. While plan mode is on, the status bar shows `⏸ plan mode on`.

The point is to separate thinking from doing. In the default mode, Claude often starts editing after a quick look around. On small tasks that’s exactly what you want. On a large change it means you find out about a wrong assumption after ten files have been touched.

## How to enter plan mode

There are three ways in, depending on how long you want to stay.

### Shift+Tab: switch the current session

Press **Shift+Tab** to cycle through permission modes. The order is:

1. Default (Claude asks before edits and commands)
2. Accept edits
3. Plan mode
4. Bypass permissions, only if you started with it enabled
5. Auto mode, only if it’s available to you

Then it wraps around to default. Stop when the status bar shows plan mode. Press Shift+Tab again to leave plan mode without approving anything.

### /plan: plan a single prompt

Type `/plan` before a prompt to plan just that request:

```
/plan migrate the session store from Redis to Postgres
```

This is handy when you mostly work in default mode and only want a plan for the occasional big task.

### Start a session in plan mode

```bash
claude --permission-mode plan
```

If you want every session to start in plan mode, set it as the default in `.claude/settings.json`:

```json
{
  "permissions": {
    "defaultMode": "plan"
  }
}
```

In the VS Code extension, set `claudeCode.initialPermissionMode` to `"plan"`.

### Plan mode compared with the other modes

| Mode | Reads and explores | Edits files | Runs commands |
| --- | --- | --- | --- |
| Default | Yes | After asking you | After asking you |
| Accept edits | Yes | Without asking | After asking you |
| Plan mode | Yes | No, only after you approve the plan | To explore; reviewed or asked first |
| Auto mode | Yes | Yes, with safety checks | Yes, with safety checks |

Plan mode is the only one where edits wait for a whole plan, not a single change. For the riskier end of the scale, see [skipping permissions in Claude Code](/en/blog/claude-code-skip-permissions/ "Claude Code skip permissions").

Shift+Tab, permission modes and the rest of the shortcuts are collected in the [Claude Code commands cheat sheet](/en/blog/claude-code-commands-cheat-sheet/ "Claude Code commands cheat sheet").

## What happens when the plan is ready

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

- **Yes, and use auto mode:** approve and let Claude work with auto mode’s safety checks. If auto mode isn’t available, this reads “Yes, auto-accept edits” instead.
- **Yes, manually approve edits:** approve, but review each edit as it comes.
- **No, keep planning:** send feedback and get a revised plan.

If you turn on the `showClearContextOnPlanAccept` setting, an extra first option approves the plan and clears the planning conversation, so the build starts with a clean context that holds only the plan.

Approving exits plan mode. A few other things worth knowing:

- **Ctrl+G** opens the plan in your editor so you can edit it directly before approving.
- Plans are saved as files, in `~/.claude/plans/` by default, or in a folder you set with `plansDirectory`.
- Accepting a plan gives the session a generated title, which makes it easier to find later.

### Shell commands during planning

Exploring often means running commands. If auto mode is available and `useAutoModeDuringPlan` is on, which it is by default, a classifier reviews those commands the way it would in auto mode. Otherwise, anything outside a set of read-only commands asks for your approval first. Either way, plan mode isn’t a sandbox for arbitrary commands; it’s a mode where Claude doesn’t edit your code.

## When to use plan mode

Plan mode is worth it when a wrong first step is expensive.

| Use plan mode | Skip it |
| --- | --- |
| Changes across several files or modules | One-line fixes and typos |
| A codebase or area you don’t know well | Code you just wrote |
| Refactors and migrations | Renaming a variable |
| Features where the approach isn’t obvious | Tasks where you already know every step |
| Anything that touches data, auth or billing | Formatting and lint fixes |
| When you want a reviewable plan before code review | Quick experiments you’ll throw away |

A good rule of thumb: if you’d sketch the change on paper before doing it yourself, ask Claude for a plan first.

Plan mode also helps when you’re learning a codebase. Ask “how does authentication flow from the login form to the session store?” in plan mode and Claude explores and explains without the risk of touching anything.

## A plan-then-execute workflow

Anthropic’s own recommended loop has four steps: explore, plan, implement, commit. In practice it looks like this.

### 1. Explore

Enter plan mode and point Claude at the area:

```
Read src/billing and the tests under tests/billing.
Explain how invoices are generated and where taxes are applied.
Don't propose changes yet.
```

Correct anything it gets wrong now. Misunderstandings are cheapest at this stage.

### 2. Plan

Ask for the plan with the constraints that matter:

```
Plan how to add per-country tax rates.
Keep the public API unchanged, add a migration, and list the tests you'd add.
```

A good plan names the files it will change, the order, the risks and how it will verify the result.

### 3. Push back

Don’t approve the first draft by reflex. Pick “No, keep planning” and say what to change: “Do the migration in a separate step”, “Don’t touch the PDF renderer”. Or press Ctrl+G and edit the plan yourself.

### 4. Execute

Approve. If you trust the plan, “Yes, and use auto mode” lets Claude work through it without stopping at every edit. If the change is risky, choose manual approval.

### 5. Verify and commit

Ask Claude to run the tests it listed in the plan. If something went wrong, Escape stops Claude, and `/rewind` (or pressing Escape twice) takes you back to an earlier checkpoint. Once it passes, commit.

For a bigger change, save the plan file and start the build in a fresh session. The plan becomes the prompt, and the build starts with a context full of decisions, not exploration.

### Use a stronger model for planning

The `opusplan` model alias uses Opus while you’re in plan mode and switches to Sonnet for execution. You get Opus-level reasoning for the decisions and Sonnet’s lower cost for the typing. Set it with `/model opusplan`. On subscriptions, that also stretches your [usage limits](/en/blog/claude-code-usage-limits/ "Claude Code usage limits").

## Plan mode and subagents

Plan mode works well with [subagents](/en/blog/claude-code-subagents/ "Claude Code subagents"), and Claude Code already uses them for it.

- **The built-in Plan subagent:** during plan mode, Claude can hand research to a Plan subagent. It has read-only tools, uses the same model as the main conversation, and does its digging in its own context, so the main conversation only gets the findings. It starts without your CLAUDE.md and without the git status snapshot, and it runs once; it can’t be resumed.
- **The Explore subagent:** another read-only built-in, tuned for quickly searching and reading the codebase.
- **Subagents stay in plan mode:** when the main conversation is in plan mode, subagents it starts stay in plan mode too. You don’t get a surprise edit from a helper.

Because research happens in separate contexts, the main conversation stays smaller. That keeps the plan focused and leaves more of the [context window](/en/blog/claude-code-context-window/ "Claude Code context window") for the build.

You can also ask for parallel research directly: “In plan mode, use subagents to look at the API layer, the database layer and the frontend separately, then give me one plan.” One caveat from Anthropic’s cost docs: agent teams with teammates in plan mode use roughly seven times the tokens of a standard session, so save that for changes that justify it.

## Plan mode and CLAUDE.md

Plan mode is only as good as the context Claude starts with. That’s where [CLAUDE.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") comes in. A few lines there make plans noticeably better:

```markdown
## Planning
- Plans list the files to change, in order, and the tests to add.
- Database changes always get their own migration step.
- Never change public API signatures without calling it out.
- Run `pnpm test` and `pnpm lint` to verify.
```

Keep two details in mind:

- The built-in Plan subagent doesn’t see CLAUDE.md, so put project-wide rules there for the main conversation, and include anything critical in your prompt when you ask for research.
- Keep CLAUDE.md short. It’s sent on every turn, so a long one costs tokens in every mode. Move long procedures into skills.

If your team always plans before building, make plan mode the default in the shared `.claude/settings.json` and describe what a good plan looks like in CLAUDE.md. Everyone gets the same behaviour without having to remember it.

## Common mistakes

- **Approving without reading.** A plan you didn’t read is just a slower default mode.
- **Planning tiny tasks.** For a typo fix, plan mode only adds a round trip.
- **Plans that are too vague.** “Refactor the auth module” isn’t a plan. Ask for files, order and verification steps.
- **Never clearing after planning.** Exploration fills the context. For big builds, approve with the clear-context option or start a new session from the plan file.
- **Assuming plan mode is a sandbox.** It stops source edits; it doesn’t turn the terminal into a safe playground. Review commands as you would anywhere else.

## Planning in AgentVera

AgentVera is a desktop app for macOS, Windows and Linux that runs Claude Code and other CLI agents side by side, per project. Each pane is the real Claude Code terminal, so Shift+Tab, `/plan` and the plan approval options work just as they do on their own. AgentVera adds structure around them:

- **[Task line](/en/features/task-line/ "Task line"):** a task moves through Analysis, Plan, Build and Review. Each stage writes its output to a file, such as `02-plan.md`, and the next stage starts from it, so the plan travels with the task instead of living in one conversation.
- **[Flows](/en/features/flows/ "Flows"):** chain steps such as research, plan and build, so the same plan-then-execute loop runs the same way every time.
- **[Auto approval](/en/features/auto-approval/ "Auto approval"):** once a plan is approved, safe reads and tests go through without prompts, while things like `git push` or `rm` still ask.
- **[Checkpoints and replay](/en/features/checkpoints-and-replay/ "Checkpoints and replay"):** the last 60 turns per agent are kept, so you can go back if a build drifts from the plan.

Checkpoints are on the free plan. Task line and auto approval are on Pro and Team. If you’re new to running several agents, start with [how to use Claude Code](/en/blog/how-to-use-claude-code/ "How to use Claude Code") and [download AgentVera](/en/download/ "Download AgentVera").

## Wrapping up

Plan mode makes Claude explore and propose before it edits. Turn it on with Shift+Tab, `/plan` or `--permission-mode plan`, read the plan properly, push back with “No, keep planning” or Ctrl+G, and only then approve. Use it for multi-file changes, unfamiliar code and anything risky; skip it for small fixes. Pair it with a short, specific CLAUDE.md, let the read-only subagents do the digging, and try `opusplan` to plan with Opus and build with Sonnet.

## Frequently asked questions

**How do I turn on plan mode in Claude Code?** Press Shift+Tab until the status bar shows “plan mode on”, type /plan before a single prompt, or start a session with claude --permission-mode plan.

**Can Claude change files in plan mode?** No. It can read files and run commands to explore, but it does not edit your source until you approve the plan.

**How do I leave plan mode?** Approve the plan, which exits plan mode and starts the work, or press Shift+Tab again to leave without approving.

**Can I make plan mode the default?** Yes. Set "defaultMode": "plan" under permissions in .claude/settings.json, and every new session starts in plan mode.

**Does plan mode use more tokens?** Planning costs some tokens up front, but on bigger tasks it usually saves more by avoiding rework. Anthropic’s cost guidance recommends it for complex changes.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/