Skip to main content

Plan Mode

Beginner
What you'll learn
  • Explain what Plan Mode does and why it is read-only
  • Decide when to plan first and when you can skip it
  • 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 makes Claude Code read-only: it can explore your codebase, run searches, and reason — but it will not edit files or run state-changing commands. Instead it produces a plan and waits for your approval.

Pro tip
  • Read-only means Claude THINKS but does not ACT — no file edits, no state-changing commands, until you say go.

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. Switch into read-only mode, then describe what you want to achieve.

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.

:::tip 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 act 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 / 4
Key takeaways
  • Plan Mode is read-only: Claude explores and proposes but never edits or runs state-changing commands until you approve
  • Use it by default for big, risky, or unfamiliar work; skip only tiny obvious edits
  • The loop is investigate to propose to approve/refine to execute
  • 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​