How to Enable and Use Planning Mode in Claude Code: A Complete Guide

Planning mode in Claude Code is a two-phase workflow that generates detailed implementation plans for your approval before executing any file changes.

The luongnv89/claude-howto repository documents how Claude Code's planning mode prevents unauthorized modifications by forcing the AI to analyze complex tasks, produce structured roadmaps with time estimates, and wait for explicit confirmation. This feature gives developers fine-grained control over large-scale refactors, API implementations, and architectural changes by separating the analysis phase from the execution phase.

Understanding Planning Mode Architecture

Planning mode operates through Claude Code's permission system, specifically the permissions.mode setting. When set to plan, the session enters a read-only state where the AI cannot write files until you approve the generated strategy.

The architecture follows a strict two-phase execution model:

• Planning Phase: Claude uses the high-quality opus model (via the opusplan alias) to analyze requirements, break work into phases, estimate time, and identify files to modify. This produces a structured implementation plan.
• Implementation Phase: After you confirm the plan, Claude switches to the faster sonnet model to execute the approved steps and write the actual code.

This split ensures you get high-quality architectural thinking without sacrificing execution speed, as documented in 09-advanced-features/README.md.

How to Enable Planning Mode in Claude Code

You can activate planning mode through three primary methods, each suited to different workflows.

Activate via CLI Flag

Start a session with planning mode locked for all subsequent prompts:

claude --permission-mode plan

This flag forces the permission manager to reject all write operations until a plan is generated and approved, as referenced in the advanced features documentation.

Activate via Slash Command

Toggle planning mode dynamically within an active session using the /plan command:

/plan Implement a user authentication system with JWT tokens

Claude immediately enters the planning phase and returns a multi-phase roadmap with estimated completion times and file lists. See 09-advanced-features/planning-mode-examples.md for sample outputs.

Configure as Default Mode

To make planning mode persistent across sessions, modify your .claude/settings.json file (project-level) or ~/.claude/settings.json (user-level):

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

This configuration is documented in 09-advanced-features/config-examples.json and ensures every new Claude Code session starts in planning-only mode.

Navigating the Two-Phase Workflow

Once enabled, the workflow strictly separates thinking from doing.

During the Planning Phase, Claude generates a structured output containing:

• Numbered phases with specific tasks
• Time estimates (e.g., "3-4 hours")
• File modification counts
• New file creation requirements

The system prompts: Ready to proceed? (yes/no/modify). If you answer yes, Claude enters the Implementation Phase and begins executing the approved steps using the faster model. If you answer modify, Claude adjusts the plan based on your feedback without writing any code.

Keyboard Shortcuts and Quick Toggles

For rapid mode switching without typing commands, use the following shortcuts while the REPL is focused:

• Shift + Tab – Cycles through permission modes including plan
• Alt + M – Alternative shortcut for Windows and Linux systems

These shortcuts provide instant access to planning mode without restarting the CLI session, as noted in 09-advanced-features/README.md.

Advanced Planning Features

The opusplan Model Alias

For optimal results on complex tasks, use the opusplan alias which automatically selects the appropriate models for each phase:

claude --model opusplan "Design and implement a REST API for a blog with real-time notifications"

This alias ensures Opus handles the heavy analytical lifting during planning while Sonnet manages the rapid execution of approved tasks.

External Plan Editing

When Claude presents a plan, press Ctrl + G (or run claude --edit-plan) to open the current plan in your system's $EDITOR. Make arbitrary changes, save, and close the editor to return to Claude with the updated roadmap. This allows you to inject specific implementation details, adjust timelines, or remove phases before execution begins.

Summary

• Planning mode in Claude Code requires setting permissions.mode to plan via CLI flag, slash command, or settings.json configuration.
• The workflow splits execution into a Planning Phase (Opus model for analysis) and an Implementation Phase (Sonnet model for execution).
• Use /plan for immediate activation, --permission-mode plan for session-wide enforcement, and defaultMode: plan for permanent defaults.
• Shift+Tab or Alt+M toggles modes instantly; Ctrl+G opens plans in external editors for manual refinement.
• The opusplan alias automatically optimizes model selection for complex planning tasks.

Frequently Asked Questions

What is the difference between planning mode and normal mode?

In normal mode, Claude Code writes files immediately after analyzing your request. In planning mode, the AI is restricted to read-only operations until it generates a detailed implementation plan and receives your explicit yes confirmation. This prevents unintended modifications to large codebases during complex refactoring tasks.

How do I permanently enable planning mode for all projects?

Add "defaultMode": "plan" to the permissions object in your global ~/.claude/settings.json file. According to the configuration examples in 09-advanced-features/config-examples.json, this setting persists across all future Claude Code sessions unless overridden by project-specific configurations.

Can I modify a plan after Claude generates it?

Yes. When Claude displays the implementation plan, you can respond with modify to request changes, or press Ctrl + G to open the plan in your preferred text editor. After editing and saving, Claude continues with your revised roadmap. This external editing workflow is documented in 09-advanced-features/README.md.

Which model does Claude use during the planning phase?

By default, Claude uses the opus model for the planning phase to ensure high-quality architectural analysis, then switches to sonnet for the implementation phase to maximize execution speed. The opusplan alias automates this model selection, as detailed in the advanced features documentation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}