Claude Code Plan Mode: Read First, Edit Second (2026)

What if the fastest way to get an agent to finish is to stop it from starting? That sounds backwards until the first time you watch a coding agent confidently refactor the wrong module for eleven minutes. Claude Code plan mode exists for exactly that failure: it lets Claude read everything, run whatever exploration it needs, and then hand you a written plan instead of a diff. You approve the approach, not the aftermath. This guide covers precisely what plan mode blocks, the three ways in, what each option on the approval prompt actually does to your session, how to edit a plan before Claude runs it, and the one situation where plan mode's blocks quietly don't apply.

What Plan Mode Actually Blocks

Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore the repository, and writes a plan; it does not edit your source. Edits stay blocked until you approve the plan.

The important nuance is that plan mode is not "read-only" in the naive sense. Claude can still run commands, which is what makes the plans good: it can check git log, run your test suite, grep for call sites, and inspect what's actually there rather than guessing from filenames. What it can't do is change anything. Commands outside the built-in read-only set prompt for approval, so you stay in the loop on the exploration too.

There's one modern wrinkle worth knowing. When auto mode is available on your account and the useAutoModeDuringPlan setting is on, which it is by default, a classifier reviews shell commands during planning instead of prompting you. Approved commands run and rejected ones are blocked. That makes planning noticeably less interrupt-heavy on accounts that qualify, and it's the reason two people can describe plan mode's prompting behavior differently and both be right.

Plan mode is one of six permission modes, and understanding where it sits on that ladder is most of the mental model; the full permissions guide lays out all six side by side.

Three Ways In: Shift+Tab, /plan, and the Flag

Pick the one that matches how long you want to stay there.

Mid-session, for a while: press Shift+Tab. That cycles default to acceptEdits to plan. The status bar tells you where you landed: ⏸ plan mode on for plan, ⏵⏵ accept edits on for acceptEdits, and a gray ⏸ manual mode on for the default mode. That gray badge trips people up, because the mode whose config value is default is labeled Manual in the CLI and the extensions. Same mode, two names.

For exactly one prompt: prefix it with /plan. This is the underrated option. You don't change the session's mode, you just make this one request go through planning, which fits the common case where 90% of your session is fine on autopilot and one request is scary.

From the start: launch with the flag.

claude --permission-mode plan

Outside the terminal, the mechanics change but the mode doesn't. In VS Code you click the mode indicator at the bottom of the prompt box and choose Plan. The JetBrains plugin runs Claude Code in the IDE terminal, so Shift+Tab works exactly as it does in a normal shell. The desktop app and claude.ai use a mode selector next to the send button.

To leave without approving anything, press Shift+Tab again. Nothing you explored is lost; you just stop being blocked.

The Approval Prompt: Your Three Options

When the plan is ready, Claude presents it and asks how to proceed. The three choices aren't cosmetic. Each one drops your session into a different permission mode, which is the part people miss.

"No, keep planning" is the option that earns plan mode its reputation. Sofia, an engineer on a payments team, uses it as a deliberate two-round ritual: the first plan is always too broad, she names the two things she doesn't want touched, and the second plan is the one she approves. She reckons it costs her ninety seconds and has twice caught a proposed schema change she'd never have spotted in a 400-line diff.

Approving a plan also names the session from the plan's content automatically, unless you already set a name with --name or /rename. Small thing, genuinely useful when you're four sessions deep.

Editing the Plan Before Claude Runs It

Press Ctrl+G at the approval prompt to open the proposed plan in your default text editor and change it directly. This is the feature most plan-mode write-ups skip, and it changes the ergonomics completely. Instead of describing an amendment in prose and hoping Claude interprets it the way you meant, you delete step 4, tighten the wording on step 2, save, and the edited plan is what gets executed.

If the showClearContextOnPlanAccept setting is enabled, the approval list gains a first option that approves the plan and clears the planning context. On a long exploration that filled the window with file reads, that's the difference between starting implementation with a clean context and starting it with 60,000 tokens of grep output still loaded. Worth knowing about before your context and memory setup starts fighting you.

Making Plan Mode the Default for a Repo

For a repository where mistakes are expensive, make planning the starting state rather than something you remember to press. Set defaultMode in .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Because that file is checked into git, everyone who opens Claude Code in that repo starts in plan mode. Put the same block in ~/.claude/settings.json instead and it applies to every project you work on. The desktop app reads the same settings files and applies the mode to new local sessions.

One asymmetry to expect: in the desktop app, a mode you pick in the selector is remembered per folder and beats defaultMode for that folder. Plan is the exception, and picking it applies only to the current session. So a checked-in "defaultMode": "plan" keeps working on desktop even after someone picks Plan manually.

Teams that go this route usually pair it with shared conventions, since a plan is only as good as the context the agent has about your codebase. Setting up a few shared skills gives the planner your team's actual patterns to plan against rather than generic ones.

Where Plan Mode Leaks

Here's the caveat that belongs in every honest write-up and appears in almost none of them: in a session where bypass permissions are available, Claude Code does not enforce plan mode's blocks. Claude is still instructed to plan without editing, but a file edit or shell command it attempts during planning runs without prompting you. Explicit ask rules and the removal circuit breaker still fire, but the guardrail you thought you had is now an instruction rather than a mechanism.

This matters because of how people actually end up in that state. You start a session with --dangerously-skip-permissions for a throwaway task in a container, keep the session alive, later switch into plan mode for something serious, and reasonably assume plan mode protects you. It doesn't, in that session. Protected-path writes follow the same pattern: normally prompted in plan mode, allowed in sessions with bypass permissions available, and routed to the classifier when auto mode is available during planning.

The other limitation is more mundane and more common. Plan mode constrains the agent, not the plan's quality. A confident, well-formatted plan built on a wrong assumption about your architecture is still wrong, and plan mode's approval prompt makes it feel reviewed. Read plans for their premises, not their steps. The steps are usually fine; the premise is where the eleven wasted minutes hide.

The Habit Worth Building

Set one threshold and stop deciding case by case: anything touching three or more files goes through plan mode. Migrations, auth, payments, and production config go through it regardless of size. Everything else runs however you normally work. That single rule captures most of the value without turning every one-line fix into a ceremony, and it's specific enough that you'll actually follow it on a Friday afternoon. Add /plan to your muscle memory for the one-off scary request, and if a repo keeps burning you, check in a defaultMode of plan so nobody has to remember at all.

Browse next: Claude Code Permissions (2026) | Claude Code Subagents (2026) | Claude Code Hooks (2026) | Claude Code Commands (2026)

Back to Blog