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

> Master Claude Code planning mode a powerful two-phase workflow. Generate detailed implementation plans and approve file changes before execution. Get the complete guide today.

- Repository: [Luong NGUYEN/claude-howto](https://github.com/luongnv89/claude-howto)
- Tags: how-to-guide
- Published: 2026-03-30

---

**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`](https://github.com/luongnv89/claude-howto/blob/main/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:

```bash
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:

```text
/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`](https://github.com/luongnv89/claude-howto/blob/main/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`](https://github.com/luongnv89/claude-howto/blob/main/.claude/settings.json) file (project-level) or `~/.claude/settings.json` (user-level):

```json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

```

This configuration is documented in [`09-advanced-features/config-examples.json`](https://github.com/luongnv89/claude-howto/blob/main/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`](https://github.com/luongnv89/claude-howto/blob/main/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:

```bash
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`](https://github.com/luongnv89/claude-howto/blob/main/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`](https://github.com/luongnv89/claude-howto/blob/main/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`](https://github.com/luongnv89/claude-howto/blob/main/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.