Skip to main content

Plan Mode

Beginner
What you'll learn
  • Explain what Plan Mode blocks — and what it still lets Claude run
  • Enter and leave Plan Mode three different ways
  • Walk through the investigate-propose-approve-execute loop
  • Tell Plan Mode and Permissions apart and use them together

The big idea​

Imagine handing a contractor your house keys versus first asking them to walk through and write up what they'd change. Plan Mode is the walkthrough.

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

Pro tip
  • Plan Mode means Claude INVESTIGATES but does not CHANGE your source — it produces a plan and waits for your go.

It is not strictly read-only​

Exploring sometimes needs a command, so Plan Mode is about not editing, not about not executing. What happens to a shell command during planning depends on the session — the first case that matches wins:

Guided walkthrough1 of 3
  1. Plan Mode's blocks are NOT enforced. Claude is still instructed to plan without editing, but an edit or command it attempts during planning runs without prompting. Plan Mode keeps its blocks everywhere else — headless -p runs, the Agent SDK, and the VS Code extension's chat panel.
Watch out
  • If you launched with --allow-dangerously-skip-permissions, Plan Mode is a strong instruction rather than a hard guardrail. Treat it as a planning convention, not a sandbox.

Why it's the safest way to start​

For anything big, risky, or unfamiliar, you want to see what Claude intends before it touches your repo. Plan Mode separates thinking from doing:

The payoff: you catch wrong assumptions before they become wrong code.

When to use it​

Pro tip
  • ALWAYS for large or multi-file changes, migrations, or refactors
  • When working in a codebase you don't fully know yet
  • When you want a reviewable plan to share with a teammate

For tiny, obvious edits you can skip it — but when in doubt, plan first.

How it works in practice​

Follow the loop. Each step earns the next — Claude only switches to editing after you approve.

Guided walkthrough1 of 4
  1. Press Shift+Tab to cycle permission modes until the status bar reads 'plan mode on', or prefix a single prompt with /plan. To start there, launch with claude --permission-mode plan. Then describe what you want to achieve.

To leave Plan Mode without approving a plan, press Shift+Tab again. To make it the default for a project's terminal sessions, set defaultMode to plan in .claude/settings.json — see Settings.

Try it yourself​

Copy this into a real planning session and watch the loop play out:

Kick off a planning session

I want to migrate our auth from sessions to JWT. Stay in Plan Mode: investigate the current setup, ask anything you need, then propose a step-by-step plan with files to change and how to verify — don't edit anything yet.
Pair it with CLAUDE.md

A good CLAUDE.md makes plans sharper — Claude plans with your conventions and guardrails already in mind.

Plan Mode vs Permissions​

A classic mix-up. They solve different problems and work together:

  • Plan Mode = "investigate and propose, don't edit yet." (This page.)
  • Permissions = once acting, which actions are allowed without asking.

Think of it as whether to act now (Plan Mode) versus which actions are allowed once acting (Permissions).

Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 5
Key takeaways
  • Plan Mode is research-and-propose: Claude reads and runs exploratory commands but does not edit your source until you approve the plan
  • It is not strictly read-only — commands during planning are classifier-reviewed, prompted, or (with bypass permissions available in an interactive terminal) unblocked entirely
  • Enter with Shift+Tab, a /plan prefix, or --permission-mode plan; approving switches the session into the mode that approve option names
  • Use it by default for big, risky, or unfamiliar work; skip only tiny obvious edits
  • Plan Mode governs WHETHER to act now; Permissions govern WHICH actions are allowed once acting

Check yourself

0/4
  1. What can Claude Code do while in Plan Mode?
  2. When should you reach for Plan Mode?
  3. What is the correct order of the Plan Mode loop?
  4. How do Plan Mode and Permissions differ?

Next​