Claude Code Plan Mode: When to Plan, Review, and Approve

In plan mode Claude can read files and run shell commands to explore, then presents its plan with the ExitPlanMode tool, which asks for your approval. Edits to your source stay blocked until you approve. Claude can still write its own plan file: by default under ~/.claude/plans/, or in the directory you set with the plansDirectory setting.

Shell commands are the subtle part. The documentation lists three cases, and the first that matches applies:

• Interactive terminal sessions with bypass permissions available (started in a way that puts bypassPermissions in the mode cycle): neither the classifier nor a prompt applies to planning commands. In these sessions Claude Code also does not enforce plan mode's blocks: Claude is still instructed to plan without editing, but an edit it attempts runs without prompting. Explicit ask rules and rm or rmdir on critical paths still prompt.
• Auto mode available and useAutoModeDuringPlan on (the default): the auto mode classifier reviews shell commands instead of prompting you; approved commands run and rejected ones are blocked.
• Otherwise: commands outside Claude Code's built-in read-only set prompt for approval, even when the sandbox's auto-allow mode is on.

So plan mode is a strong guard in normal sessions and a polite request in a terminal session where you made bypass available. If you rely on it as a safety boundary, do not start those sessions with bypass enabled.

There are four ways in, depending on how long you want to plan:

• One prompt: prefix it with /plan, for example /plan add rate limiting to the public API.
• Mid-session: press Shift+Tab to cycle permission modes until the status bar shows ⏸ plan mode on. From auto mode, the first press goes to manual (default), then acceptEdits, then plan. Press Shift+Tab again to leave without approving.
• A whole session: start with the flag.

1claude --permission-mode plan

• Every session in a project: set the default mode in .claude/settings.json:

1{2  "permissions": {3    "defaultMode": "plan"4  }5}

Surfaces differ slightly. The VS Code extension does not read project settings for its starting mode; set claudeCode.initialPermissionMode to plan in your VS Code user settings instead. In the desktop app, choosing Plan in the mode selector applies to the current session only, while other choices are remembered per folder.

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

• Yes, and use auto mode: approve and continue in auto mode. If auto mode is not available to your session, this reads Yes, auto-accept edits instead.
• Yes, manually approve edits: approve and review each edit as it happens.
• No, keep planning: stay in plan mode and tell Claude what to change.

Approving exits plan mode and switches the session to the mode that option describes, so the choice is also a decision about how much oversight the execution gets. To plan again later, cycle back with Shift+Tab or prefix a prompt with /plan.

Two more controls are worth knowing. Ctrl+G opens the proposed plan in your default text editor so you can edit it directly before Claude proceeds: faster than describing a change when you want to delete a step or reorder two. And the showClearContextOnPlanAccept setting adds a first option that approves the plan and clears the planning context, so execution starts with the plan rather than every file Claude read while making it. That helps on long planning sessions that filled the context window; see Claude Code Context Window.

Accepting a plan also gives the session a generated title based on the plan, unless you already named it.

The documentation describes the mechanism; whether the plan is any good depends on what you ask for. The following is our practical advice rather than documented behaviour.

Ask for a plan you can check. A useful prompt names the goal, the constraints, and the shape of the answer:

1/plan Add per-API-key rate limiting to the public REST API.2Constraints: keep the existing middleware order; no new infrastructure beyond Redis.3In the plan, list: files to change, new tests and how to run them,4the migration or config changes, risks, and what is explicitly out of scope.

Then review it like a design doc, with a short checklist:

1. Files: does it touch what you expected, and nothing surprising? 2. Verification: does it say how success will be checked (tests, commands, manual steps)? 3. Assumptions: did it read the code it depends on, or guess? Plans that cite file paths and function names are grounded; vague ones are not. 4. Scope: is anything missing, or added that you did not ask for?

If the codebase is large, ask Claude to delegate exploration to a subagent during planning so the reading happens in a separate context and only findings return; see Subagents Explained.

The opusplan model setting uses Opus while the session is in plan mode and switches to Sonnet for execution. The idea is to spend the stronger model on design decisions and the faster one on carrying them out.

1claude --model opusplan2# or inside a session3/model opusplan

Each phase uses its own model's context window. The documentation notes that on the Anthropic API the current Opus and Sonnet models run with a 1M-token context window by default; where they do not, opusplan[1m] requests it for both phases. If your organisation restricts models with availableModels and excludes the newest Opus, opusplan uses the newest permitted Opus on the Anthropic API and Claude Platform on AWS; on Bedrock, Google Cloud, and Foundry, planning stays on the session's model when the upgrade is excluded.

The trade-off is cost and usage limits: the planning phase runs on the more expensive model and counts against Opus limits, and the documentation notes that some usage-limit shortcuts do not apply under opusplan (for example, waiting for a reset instead of resuming early after switching models).

Plan mode keeps its blocks wherever Claude Code runs without an interactive terminal: claude -p, the Agent SDK, and the VS Code chat panel. In the Agent SDK, file edits are never auto-approved in plan mode, even if an allow rule matches or a PreToolUse hook returns allow; they go to your canUseTool callback instead. Recent versions route file-modifying shell commands such as touch and rm to the callback the same way.

That makes plan mode a convenient way to get a design out of an agent without risking changes:

1import { query } from "@anthropic-ai/claude-agent-sdk";2 3for await (const message of query({4  prompt: "Plan how to split src/billing into its own package. Do not change files.",5  options: { permissionMode: "plan" },6})) {7  if (message.type === "result" && message.subtype === "success") {8    console.log(message.result); // the plan, for a human or a later run9  }10}

A two-stage pipeline (plan in one run, review the output, then execute in a second run with an edit-capable mode) gives you a human checkpoint in automation. For more on SDK permission handling, see Claude Agent SDK Quickstart.

Plan mode costs one extra round trip plus the planning tokens. It pays off when the plan contains information you do not already have (which files, in which order, what could break) or when you need to sign off before anything changes. It is wasted on changes you would have described exactly anyway.

A good middle path is plan, then hand off: approve the plan into auto mode, or give it to a subagent or a separate worktree session, and review the resulting diff. The plan becomes the specification, and your review moves from every edit to the plan and the final change. For running that work in parallel, see Claude Code Worktrees.

Pick a change in a repository you know that touches at least three files.

1. Run /plan with the prompt pattern above (files, tests, risks, out of scope). 2. Review with the four-point checklist. Use Ctrl+G to delete or reorder at least one step, then choose Yes, manually approve edits. 3. Note any edit Claude made that was not in the plan. 4. Repeat on a second change, but approve into auto mode and review only the final diff. 5. Run one plan through the Agent SDK with permissionMode: "plan" and confirm no files changed (git status).

Pass criterion: you can state, for your own work, which kinds of changes you will plan first, which approval option you will use for each, and whether the extra round trip paid off.