Claude Lessons / Guides

Claude Code Plan Mode: How It Works and When to Use It

Claude Lessons team · Updated August 13, 2026

Plan mode is Claude Code's read-only gear: Claude can read, search, and reason about your codebase, but nothing gets edited until you approve a written plan. Most people discover it with an accidental Shift+Tab, escape out, and never come back — and then wonder why a colleague's agent-written PRs look surgical while theirs need three rounds of cleanup. This guide covers the mechanics (every way in and out, what each approval option actually does) and the judgment: which tasks repay the extra round-trip, which don't, and how to review a plan so that approving it means something.

What plan mode actually is

Plan mode tells Claude Code to research and propose changes without making them. In this mode Claude reads files, searches the repo, and runs exploratory commands — but file edits are blocked by the tool itself until you approve the plan it produces. Three properties make it more than "chat before you code":

• It's enforced, not requested. The edit tools are gated by the harness. You're not relying on the model remembering an instruction like "don't change anything yet" — it structurally can't.
• It produces an artifact. The plan is a discrete, structured proposal — which files, what changes, in what order — that you can read, push back on, edit directly, and re-issue. Not a paragraph buried in scrollback.
• Exiting is an explicit gate. Claude doesn't quietly start editing. You approve, keep iterating, or walk away. That checkpoint is the whole point: your judgment intervenes at the moment it's cheapest — before any code exists.

"Read-only" has one nuance worth knowing. Truly read-only commands (listing files, git status, searching) run freely. For other exploratory commands, behavior depends on your setup: where auto mode is available, a safety classifier reviews commands during planning and lets harmless ones run; otherwise anything outside the built-in read-only set prompts you first. Edits, either way, wait for your approval.

Where it sits among the permission modes

Plan mode is one of Claude Code's permission modes — the settings that control how much Claude does without asking. Seeing the whole ladder makes plan mode's role obvious: it's the deliberate end of a spectrum that runs all the way to full autonomy.

Entering and exiting plan mode

Four ways in, one way out:

• Shift+Tab during a session. Cycles permission modes — default → acceptEdits → plan — and the status bar shows ⏸ plan mode on when you land on it. Press Shift+Tab again to leave without approving anything.
• /plan as a prompt prefix. Plans just that one request: /plan add rate limiting to the public API. Good for one-off planning without changing the session's mode.
• At startup. claude --permission-mode plan starts the session already in plan mode. The same flag works with -p for non-interactive runs.
• As a default. In a repo where you want everyone scoping before changing, set it in .claude/settings.json:

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

In the VS Code extension, use the mode indicator at the bottom of the prompt box (the label is "Plan"), or set claudeCode.initialPermissionMode. In the desktop app, it's the mode selector next to the send button.

What happens when the plan is ready

When Claude finishes planning, it presents the plan and asks how to proceed. The options are doing more than they look like — each one sets the permission mode the execution phase will run in:

Three lesser-known details that make the approval step more useful:

• Ctrl+G opens the plan in your editor. Instead of describing changes in chat, edit the plan text directly — reorder steps, delete a section, add a constraint — and Claude proceeds from your version.
• Approving names the session. Accepting a plan automatically names the session from the plan's content (unless you've already named it), which makes /resume much less of a guessing game later.
• To plan again, just cycle back. Approval switches the session out of plan mode. For the next risky task, hit Shift+Tab back to plan, or prefix the prompt with /plan.

When plan mode pays off — and when to skip it

The rule of thumb: use plan mode when being wrong costs more than one extra round-trip. Concretely, five categories clear that bar almost every time:

• Anything touching more than one file. Multi-file scope means multiple judgment calls; a plan lays them all out while correcting any of them is still free.
• "Follow the existing pattern" tasks. Without a plan, Claude guesses what your pattern is and codes against the guess. With one, it reads three existing examples, states its inference, and you correct the inference — not the shipped code.
• Refactors. A plan that names every call site is checkable for completeness before anything moves. Half-applied refactors are the most expensive kind of almost-right.
• Fuzzy requirements. When you're not sure what you want, the plan is a requirements probe: it comes back assuming something, the assumption surfaces the ambiguity, and the next plan is sharper. You're using a read-only loop as a cheap simulator of shipping.
• Anything production-adjacent. Migrations, auth, config, data handling. You want the enforced checkpoint, and you want to read the plan twice.

And skip it, without guilt, when:

• The fix is mechanical. A typo, a constant, a one-line change you could type yourself. Planning here is ceremony.
• You're just asking questions. "Where does auth middleware live?" is already read-only; plan mode adds nothing.
• Your prompt is the plan. "Edit file X, function Y, change Z to W" — asking for a plan gets your prompt read back to you.

How to review a plan (a working rubric)

Plan mode's value is exactly proportional to how seriously you read the plans. Rubber-stamping gets you the overhead with none of the protection. Read a plan the way a good reviewer reads a PR description, checking five things:

• Complete file list. Every file it will touch, by name. "…and related files" is an automatic reject — that phrase is where surprise diffs come from.
• Order of operations, with verification. What gets changed first, and what check (test, build, manual step) confirms each stage before the next.
• Evidence it read the code. A trustworthy plan cites specifics: "the admin API already does this in rate-limit.ts, I'll extract and reuse it." A plan with no file paths in it was written from pattern-matching, not reading.
• Test impact, named. Which tests change, which get added, which might break for acceptable reasons.
• What it won't touch. Boundaries matter as much as scope — if a file is owned by another team or a migration is out of bounds, the plan should say so, and you should say so if it doesn't.

Then push back in the plan, not in the diff. "Item 3 breaks existing cache keys — use a versioned prefix instead" takes five seconds before any code exists. The same correction after execution is a real diff to review, and possibly a revert. The cheapest place to fix a bug is the plan; the second cheapest is the first file; the most expensive is the merged PR.

Getting better plans out of Claude

Weak plans are usually an input problem. Four fixes, in order of leverage:

• Ask for the shape you want. "Plan this with: the list of files to edit, the functions modified in each, order of operations, and test impact." Once you set the bar, the plan meets it — and you can encode that bar permanently in CLAUDE.md so every future plan has those sections.
• Write the divergence rule into CLAUDE.md. The highest-leverage sentence you can add: "If execution diverges from an approved plan, stop and re-enter plan mode instead of improvising." Plans drift when reality surprises the agent mid-task; this rule turns silent improvisation back into a visible checkpoint. See our CLAUDE.md best practices guide for how to write rules that actually hold.
• Give verification targets. A plan written against "make the tests in auth.test.ts pass without modifying them" is concrete in a way "fix the auth bug" never will be.
• Treat wrong assumptions as documentation bugs. When a plan assumes the wrong ORM pattern or the wrong user type, correct it — then capture the correction in CLAUDE.md so the next plan doesn't repeat it. Plan mode is where your project's undocumented knowledge becomes visible; that's a gift if you write it down.

Plan mode, cost, and the rest of the toolkit

Cost. Planning isn't free — a good plan means Claude read a lot of files — but the most expensive token in agentic coding is the one spent confidently executing the wrong approach. A rejected plan costs one read-only pass; a rejected implementation costs the execution, the review that caught it, and the do-over. Plan mode is also why the second prompt often feels fast: the files read during planning are already in context when execution starts. For the full picture of where tokens go, see our token usage and costs guide.

Recovery. Plan mode reduces wrong turns; it doesn't eliminate them. When execution goes sideways anyway, press Escape to stop, and use /rewind to restore code and conversation to a checkpoint instead of arguing the session back to health. Checkpoints and context hygiene are covered in the context management guide.

Delegation. For large features, the strongest pattern is planning at two levels: plan the decomposition in your main session, then hand each slice to a subagent with a tightly-scoped task. You review one architecture plan and several small, focused pieces of work instead of one giant unreviewable blob. One cost note if you run multi-agent setups: parallel agents each carry their own context, so planning with a whole team runs several times the tokens of a solo session — plan solo, execute in parallel.

Common mistakes

• Rubber-stamping. Approving plans you didn't read is the worst of both worlds: all of the overhead, none of the protection. If you catch yourself doing it for a category of task, stop using plan mode for that category — or start reading.
• Using it for everything. Plan mode on a typo fix teaches you that plan mode is annoying, and that lesson costs you the habit right before the task that needed it.
• Blaming the plan for a vague ask. "Improve the auth flow" produces a vague plan because it's a vague request. The plan didn't fail — it surfaced the problem early, which is its job.
• Letting execution drift silently. If diffs stop matching the approved plan, that's improvisation. Add the divergence rule to CLAUDE.md and expect Claude to come back to you when reality disagrees with the plan.
• Confusing plan mode with a security boundary. Plan mode blocks writes, not reads — it is a workflow gate, not an isolation mechanism. Scoping what Claude can access and run is a permissions question; see the security best practices guide.

FAQ

What is plan mode in Claude Code?

Plan mode is a permission mode in which Claude Code researches and proposes changes without making them. Claude can read files, search the codebase, and run exploratory commands, but file edits stay blocked until you approve a written plan. It's enforced by the tool itself — the model can't edit its way around it — which makes it different from just asking Claude to describe an approach in chat.

How do I turn on plan mode?

Four ways: press Shift+Tab in the CLI to cycle permission modes until the status bar shows plan mode; prefix a single prompt with /plan to plan just that request; start a session with claude --permission-mode plan; or make it the default by setting permissions.defaultMode to "plan" in .claude/settings.json. Press Shift+Tab again to leave plan mode without approving a plan.

Can Claude Code still run commands in plan mode?

Yes, within limits. Read-only commands (listing files, checking git status) run freely so Claude can explore. Where auto mode is available, a safety classifier reviews other exploratory commands during planning and approves or blocks them; otherwise, commands outside the read-only set prompt you for approval. What plan mode reliably blocks is edits: file writes wait until you approve the plan.

What happens when I approve a plan?

Claude presents the finished plan with options: approve and run in auto mode (or auto-accept edits where auto mode isn't available), approve but manually review each edit, or keep planning. Approving exits plan mode, switches the session into the mode you picked, and Claude executes the plan. You can also press Ctrl+G to open the proposed plan in your text editor and modify it directly before approving.

Is plan mode the same as asking Claude what it would do?

No. A chat answer is advisory — nothing stops Claude from drifting once it starts editing. Plan mode is a harness state: edits are blocked by the tool until you approve, the plan is a discrete artifact you can edit and re-issue, and exiting is an explicit gate. The discipline comes from enforcement, not from the model's good intentions.

Does plan mode reduce Claude Code costs?

Usually, yes — indirectly. Planning itself costs tokens (Claude reads a lot of files to write a good plan), but the most expensive thing in agentic coding is confident execution in the wrong direction: a bad approach implemented, reviewed, and reverted burns far more than one planning pass. The files read during planning also stay in context, so approved plans execute with less re-exploration.