Safely Analyze Code with Plan Mode

Plan mode instructs Claude to create a plan by analyzing the codebase using read-only operations. It is ideal for exploring codebases, planning complex changes, or safely reviewing code.

When to Use Plan Mode

• Multi-step implementation: When your feature requires editing many files
• Code exploration: When you want to thoroughly research the codebase before changing anything
• Interactive development: When you want to iteratively discuss direction with Claude

How to Use Plan Mode

Toggle Plan Mode During a Session

You can use Shift+Tab to cycle between permission modes during a session.

If you are in normal mode, Shift+Tab will first switch to auto-accept mode, displaying ⏵⏵ accept edits on at the bottom of the terminal. Press Shift+Tab again to switch to plan mode, displaying ⏸ plan mode on.

Start a New Session in Plan Mode

To start a new session in plan mode, use the --permission-mode plan flag:

claude --permission-mode plan

Run a “Headless” Query in Plan Mode

You can also run queries directly in plan mode using -p (i.e., “headless mode”):

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

claude --permission-mode plan

> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

> What about backward compatibility?
> How should we handle database migration?

Configure Plan Mode as the Default

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

See the settings documentation for more configuration options.