Plan Mode

Using plan mode for read-only exploration and design before writing code.

Plan mode is a read-only exploration mode for designing your approach before writing any code. It prevents wasted work by getting alignment on the strategy first.

When to use plan mode

  • Complex tasks with unclear scope
  • Multiple valid approaches where you want to evaluate tradeoffs
  • Multi-file changes where the order and structure matter
  • Refactoring or architecture changes where mistakes are expensive
  • Any task where you would normally sketch on a whiteboard first

How it works

There are three ways to enter plan mode:

/plan                              # During a session
Shift+Tab (cycle to plan mode)     # Toggle with keyboard
claude --permission-mode plan      # At launch

In plan mode, Claude:

  • Explores the codebase (reads files, searches, analyzes)
  • Designs an implementation approach
  • Presents the plan for your approval
  • Does NOT write or modify any files

Once you approve the plan, Claude exits plan mode and implements it. Press Ctrl+G to open the plan in your default text editor, where you can edit it before Claude proceeds.

Example: Planning a database migration

/plan

I need to split the users table into users and user_profiles.
The users table currently has 47 columns. I want to move all
non-auth columns to user_profiles with a foreign key back to users.

Consider:
- Which columns move vs. stay
- What queries need to change
- How to handle the migration without downtime
- What tests need updating

Claude will explore the schema, find all queries that reference the affected columns, identify test files, and present a migration plan — all without changing a single file.

Plan mode vs. just asking

You can always ask Claude to plan without entering plan mode. The difference:

  • Plan mode enforces read-only — Claude literally cannot write files
  • Asking “plan this” relies on Claude’s judgment not to jump ahead
  • Use plan mode when the stakes are high and you want the guarantee

Tips

  • Use plan mode at the start of any task that touches more than three files.
  • After approving a plan, ask Claude to implement in stages rather than all at once.
  • Plan mode pairs well with the explore-plan-code-commit workflow — it formalizes the first two phases.
  • If Claude’s plan reveals unexpected complexity, you can adjust scope before any code is written.
Used in