Claude Code plan mode: plan first, then edit

What is plan mode in Claude Code?#

Plan mode is one of Claude Code’s permission modes, the settings that decide what Claude may do without asking. In the docs’ words, it “tells Claude to research and propose changes without making them”: Claude reads files, runs shell commands to explore and writes a plan, but doesn’t edit your source. When the plan is ready, Claude presents it and asks how to proceed.

The point is a checkpoint. You see the approach (which files, in what order, what tests) while changing it costs a sentence, not a rewrite. It suits work you don’t yet understand: an unfamiliar codebase, a change across many files, or a bug whose cause isn’t obvious.

How do I turn on plan mode? Shift+Tab, /plan and --permission-mode#

• Shift+Tab cycles the modes: default → acceptEdits → plan, then bypassPermissions and auto if they’re available. From auto, the first press goes to default. The status bar shows ⏸ plan mode on. Press Shift+Tab again to leave without approving a plan.
• Alt+M does the same on Windows when the terminal’s runtime doesn’t enable VT input mode, which is when Shift+Tab doesn’t register.
• `/plan` enters plan mode from the prompt. Add a description to start straight away: /plan fix the auth bug.
• `claude --permission-mode plan` starts a session in plan mode. The flag overrides defaultMode from settings files.
• `defaultMode` in settings makes plan mode the default for every session in a project (shown below). In the VS Code extension, set claudeCode.initialPermissionMode to plan instead, because the extension doesn’t read project settings for this. In the desktop app, picking Plan applies to the current session only.

# Start a session in plan mode
claude --permission-mode plan

# Or, inside any session, plan one task
/plan add rate limiting to the login endpoint

{
  "permissions": {
    "defaultMode": "plan"
  },
  "plansDirectory": "./plans"
}

plansDirectory is optional: it puts plan files in your project (a path relative to the project root) instead of the default ~/.claude/plans, which is handy if you want to review or commit them. The Claude Code settings builder writes and checks this file for you.

What can Claude do in plan mode, and what is blocked?#

Reading is allowed and editing is blocked. Shell commands depend on your setup, and the docs give the rules in order (the first that applies wins):

Without an interactive terminal the blocks always hold: in -p runs, Agent SDK sessions and the VS Code extension’s chat panel. On Enterprise, API and cloud-provider accounts, the classifier calls made during planning count toward your token usage. Inside the session, Claude often hands the research to the built-in Plan subagent: read-only tools, your session’s model, and a separate context window, so the exploration doesn’t fill yours. Our subagents guide covers it and the other built-ins.

How do you approve, edit or reject a plan?#

When Claude finishes, it shows the plan and offers these choices. Approving exits plan mode and switches the session to the mode the option names:

To change the plan yourself, press Ctrl+G: it opens the proposed plan in your default text editor, and Claude proceeds from your edited version. The clear-context option is worth turning on for long research: the docs warn that planning can use a lot of context, and the option shows how much of yours the planning used. If a session fills up anyway, see Prompt is too long.

When should you use plan mode?#

Use it when getting the direction wrong would be expensive. Anthropic’s cost docs put it plainly: plan mode suits complex tasks because it prevents “expensive re-work when the initial direction is wrong”. Skip it for small, obvious edits, where the plan would be longer than the change.

A worked example: explore, plan, then code

1. Run /plan add rate limiting to the login endpoint. Claude reads the routes, middleware and tests, and may delegate the search to the Plan subagent.
2. Read the plan. Ask questions (“why a new middleware instead of the existing limiter?”) and choose No, keep planning until it matches what you want, or press Ctrl+G and edit it.
3. Choose Yes, manually approve edits for risky code, so you review each change, or the auto option for routine work.
4. Ask Claude to run the tests. For a big plan, the clear-context option, or saving the plan and running /clear, starts the implementation with the plan and none of the exploration.

Put the rule in your project instructions if you always want it for some code, for example “Use plan mode before changing anything under src/billing/.” Our guide on how to write CLAUDE.md explains where such rules go.

Plan mode vs the other permission modes#

Plan mode is the only mode built for proposing rather than doing. The others differ in how much Claude may do without asking:

Plan mode doesn’t replace permission rules: your allow and deny rules still apply in every mode. The settings builder explains each mode and writes defaultMode and the rules into one file.

Does plan mode save tokens? opusplan and the Plan subagent#

Plan mode uses tokens like any other turn: Claude still reads files and writes a plan. It saves them when it stops a wrong approach before Claude rewrites files, and the Plan subagent keeps the exploration’s file reads out of your main context. It doesn’t make a session cheaper by itself.

The opusplan model setting pairs well with it: it “uses opus during plan mode, then switches to sonnet for execution”. On the Anthropic API those aliases are currently Opus 5.5 and Sonnet 5.5; on Bedrock, Google Cloud and Microsoft Foundry they map to older models. Choose it with /model opusplan. Each switch is a model change with its own prompt cache, which how to reduce Claude Code token usage explains, along with what plans and subscriptions cost in Claude Code pricing.

One cost to know: Anthropic’s costs docs say agent teams use about seven times the tokens of a standard session when teammates run in plan mode, because each teammate plans in its own context window.