Plan Mode in Claude Code for Complex Tasks

Plan Mode is a read-only permission state in Claude Code: Claude can read files, search the codebase, run read-only shell commands, use web search, and ask clarifying questions, but it cannot write or edit your source or run state-changing commands until you approve its plan.

Most developers meet it the hard way. You ask for one change, glance away, and come back to find the agent has quietly rewritten half a dozen files on assumptions you never got a chance to question. Plan Mode puts a pause between “here’s what I want” and the first edit that lands on disk, which is usually the moment things go sideways. This article covers what Plan Mode is, the four ways to turn it on, the real read-only boundary (prompt- and permission-enforced, not a hard sandbox), a workflow for multi-file refactors, and when a plan is pure overhead.

What is Plan Mode in Claude Code?

Plan Mode is one of Claude Code’s permission modes, sitting alongside acceptEdits, auto, dontAsk, and bypassPermissions, rather than a separate product surface. Inside it, Claude explores the codebase and drafts a proposal, and edits to your source stay blocked until you approve that proposal. Shell commands are handled on a separate track: where auto mode is available during planning, a classifier vets each command instead of interrupting you, and otherwise anything outside Claude Code’s built-in read-only set stops for your approval.

The value is review before execution. Claude Code’s recipe for planning before you edit is aimed at exactly this case, changes you want to inspect before anything lands on disk. That gates the compounding-error problem: on a change with many decision points, each wrong guess early corrupts everything downstream, and a plan lets you correct the guesses on paper instead of in a diff.

How do you turn on Plan Mode?

There are four ways to enter Plan Mode, and they differ in scope. Pick the one that matches how long you want the mode to stick.

The official docs confirm the cycle order: Shift+Tab moves default → acceptEdits → plan, so two presses from the starting mode land you in Plan Mode, with the current mode shown in the status bar. Note the label: the default mode now displays as Manual in the CLI and IDE extensions, though its config value is still default. For a project default, the key is nested. Set it in .claude/settings.json under "permissions": { "defaultMode": "plan" }, not at the top level.

What Plan Mode Can and Can’t Do

In Plan Mode Claude keeps its read and research tools (Read, Grep, Glob, Task/subagents, WebSearch, and WebFetch), while its Write, Edit, and Bash-for-changes tools are held back until you approve. State-changing MCP tools are held back the same way. The exact tool inventory is a property of the harness and shifts between versions, so treat that as the general set rather than an exhaustive contract.

The boundary is enforced by an injected system instruction plus Claude Code’s permission system rather than a hard sandbox, which is why the plan itself is written to an editable markdown file rather than being blocked as a “write.” Armin Ronacher’s teardown of the plan-mode implementation found the write tools are still present and that entering plan mode injects a prompt telling the model it is read-only; the edit tool is what Claude uses to author its own plan file. The docs corroborate that this is permission-layer, not tool-removal: in a standard session, writes to protected paths still route through the prompt system rather than being silently dropped. Practically, that means the plan is a plain-text contract you can edit. Press Ctrl+G to pull the proposed plan into your text editor, annotate or delete steps, and Claude picks up your changes before it writes any code.

A Plan Mode Workflow for Complex Tasks

For a multi-file change, the loop is describe → clarify → plan → edit → execute:

1. Describe the task in Plan Mode and point Claude at the relevant files. State the goal and the constraints in the first prompt.
2. Let Claude read and ask. It traces imports, then surfaces the genuinely ambiguous decisions (architecture depth, what to do with dead code, which test framework) before committing to an approach. A weak sign is a plan that names only files, never specific functions.
3. Review the numbered plan. Check that steps are ordered by dependency and that tests are interleaved with implementation, not tacked on at the end.
4. Edit and approve. Use Ctrl+G to annotate or reorder, then approve when the contract reads correctly.
5. Execute and watch for drift. Claude works step by step against the approved plan.

Approving a plan exits Plan Mode, so if execution drifts (Claude edits a file the current step didn’t mention, or silently makes a call the plan left open) press Shift+Tab to re-enter Plan Mode and have Claude re-plan the remaining work against the current state of the files. Re-planning mid-task is normal on real refactors, not a failure mode. For work too large for one session, split it into sequential plans rather than one sprawling document.

Split Planning and Execution Across Models

For complex work, use the strongest reasoning model to draft the plan and a faster, cheaper model to carry it out: planning quality dominates outcomes, while execution is largely mechanical once the plan is right. Claude Code ships this as a model alias rather than a toggle. Selecting opusplan runs the opus model while you are in plan mode and switches to sonnet the moment execution begins.

On the Anthropic API, opus resolves to Claude Opus 5 and sonnet resolves to Claude Sonnet 5, so opusplan gives you Opus 5 for planning and Sonnet 5 for execution. Opus 5 requires Claude Code v2.1.219 or later; on earlier releases the opus alias still points at Opus 4.8. Aliases track the recommended version for your provider and move as new models ship, so pin a full model name such as claude-opus-5 when you need a fixed version. Opus is not the top of the lineup either: the models overview puts Claude Fable 5 above the Opus tier as Anthropic’s most capable widely released model, and Claude Code exposes it through the fable alias for work larger than a single sitting.

When to Use Plan Mode vs When to Skip It

Use Plan Mode when a change touches roughly three or more files, involves a refactor, schema migration, or security-sensitive work, or can’t be described in a single sentence; skip it for one-line fixes and mechanical edits where a plan is pure overhead. Three files is roughly where compounding decisions start to bite. Typo corrections, isolated function tweaks, and a rename across one file are faster without the planning round-trip. Anything where you’re unsure how the codebase handles a specific case, or where a premature edit would be expensive to unwind, is worth planning first.

The one-sentence rule is the fastest filter: if you can state the entire change in a single sentence, just make it; otherwise, plan it. Scale past that only when a plan genuinely outgrows a single execution context, at which point Claude Code’s experimental Agent Teams distributes the work across instances, with the lead reviewing and approving each teammate’s plan before it starts writing.

Reach for Plan Mode on your next multi-file change, edit the plan with Ctrl+G before granting write access, and cycle back with Shift+Tab the moment execution wanders. The mechanics change often, so confirm any version-gated specifics against the official Claude Code docs before you rely on them.

FAQs

Does Plan Mode actually prevent Claude from editing files, or can it still write?

Plan Mode blocks edits to your source but is not a hard sandbox. The read-only boundary is enforced by an injected system instruction plus Claude Code's permission system, not by removing the write tools. The edit tool is still present, which is how Claude authors its own plan file, and any attempted write to your code still routes through the permission prompt rather than being silently allowed.

What is the difference between using Shift+Tab, the /plan prefix, and the --permission-mode plan flag?

They differ in scope. Pressing Shift+Tab cycles the mode for the current session and persists until you cycle again. The /plan prefix applies to only the single next prompt, leaving your mode unchanged. Starting with claude --permission-mode plan puts the whole session in plan mode from launch. For a standing default, set permissions.defaultMode to plan in settings.json so it applies to every session in the project or user scope.

How do I make Plan Mode the default for a project?

Set defaultMode to plan inside the permissions object in .claude/settings.json, written as permissions containing defaultMode set to plan. The key is nested under permissions, not placed at the top level of the file. Once set, every session started in that project begins in Plan Mode automatically. Use a user-level settings file instead if you want plan-first behavior across all your projects rather than one repository.

What happens after I approve a plan, and how do I get Claude to re-plan mid-task?

Approving a plan ends the planning phase and moves the session into whichever permission mode the approval option you picked describes, so Claude gets to work straight away. If execution drifts from the agreed steps, press Shift+Tab to re-enter Plan Mode, or prefix your next prompt with /plan, and have Claude re-plan the remaining work against the current state of the files. Re-planning mid-task is expected on real refactors, not a failure.

Which model should draft the plan versus execute it?

Use the strongest stable reasoning model to draft the plan and a faster, cheaper model to execute it, since planning quality dominates outcomes while execution is largely mechanical. Claude Code automates the handoff through the opusplan model alias, which runs Opus during plan mode and switches to Sonnet for execution. On the Anthropic API those aliases resolve to Claude Opus 5 and Claude Sonnet 5 respectively. Aliases move as new models ship, so pin a full model name when you need a fixed version.