Claude Code Plan Mode: The Complete Developer Guide (2026)

Plan Mode sits at the edge of how most developers use Claude Code. It is not the default. It requires an extra gesture to activate. And it makes Claude slower, at least at the start — the whole point is to add a review step before execution.

Yet the developers who use Plan Mode consistently report fewer costly mistakes, better understanding of what Claude is about to do, and more predictable outcomes on complex tasks. This guide explains why, covers all five activation methods, and shows you when the overhead is worth it.

What Plan Mode Actually Does (and What It Does Not)

The Guarantee: Read Without Writing

Plan Mode is a permission mode, not a prompt instruction. When you activate it, Claude Code enforces a constraint at the system level: Claude can read files, run exploratory shell commands, and write a plan document, but it cannot edit your source files.

This is not Claude trying to follow a rule you stated in conversation. It is a permission mode that the system enforces — the same way acceptEdits mode auto-approves file edits, Plan Mode blocks them. Claude cannot accidentally drift out of it mid-task.

What Claude can do in Plan Mode:

• Read files with the Read tool
• Run read-only shell commands (cat, grep, find, git log, git diff, etc.)
• Write a plan document to the plansDirectory
• Propose the plan and present the approval dialog

What Claude cannot do in Plan Mode:

• Edit, create, or delete source files
• Run commands with side effects (file writes, network requests, package installs)
• Proceed past the plan without your approval

What It Does Not Replace

Plan Mode is not a substitute for CLAUDE.md. CLAUDE.md tells Claude how to work in your codebase permanently. Plan Mode is a per-session or per-task gate that lets you review the approach before execution starts.

Plan Mode is also not the same as asking Claude to “think step by step” or “explain before doing.” Those are conversational prompts that influence Claude’s reasoning but do not enforce any constraint on tool use. Plan Mode is a hard permission boundary.

All 5 Ways to Activate Plan Mode

Method 1: Shift+Tab (Mid-Session Toggle)

The fastest activation during an active session. Press Shift+Tab to cycle through permission modes: default → acceptEdits → plan. Press it again to keep cycling. The current mode appears in the status bar.

This is the most common activation pattern for experienced users. Start a session in default mode, then drop into plan mode when you hit a task that warrants review before execution.

# In an active Claude Code session:
# Press Shift+Tab once or twice to reach plan mode
# Status bar shows: ◇ plan

To leave plan mode without approving a plan, press Shift+Tab again to cycle to the next mode.

Method 2: /plan Prefix (Single-Prompt Plan)

Prefix any prompt with /plan to activate plan mode for that prompt only:

/plan refactor the authentication module to use the new token service

Claude enters plan mode, produces the plan, and shows the approval dialog. After you act on the plan (approve, refine, or reject), plan mode exits automatically. Your next prompt runs in whatever mode you were in before.

This is the cleanest option for one-off planning on a specific task without permanently switching modes.

Method 3: —permission-mode plan (Startup Flag)

Start a session in plan mode from the CLI:

claude --permission-mode plan

Everything in the session runs in plan mode until you change it. Useful when you know upfront that the session is for planning — exploring a codebase, reviewing a proposed approach, or producing a planning artifact for handoff to another session.

This flag also works with -p for non-interactive runs:

claude -p --permission-mode plan "Plan a migration of the payment module to the new API"

In non-interactive mode, Claude explores, produces the plan, and outputs it to stdout without presenting an approval dialog.

Method 4: defaultMode in Project Settings

Set plan mode as the default for a specific project by adding defaultMode to .claude/settings.json:

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

Every session started in that project directory begins in plan mode. The mode indicator reminds you on each session start. You can still switch modes mid-session with Shift+Tab.

This is useful for projects where you consistently want a review gate — production codebases, shared repositories, or projects where you are learning the codebase and want to understand what Claude is about to do before it does it.

Method 5: defaultMode in User Settings (Global Default)

Set plan mode as the global default across all projects in ~/.claude/settings.json:

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

Every new session starts in plan mode regardless of the project. Most users prefer this as a personal safety default rather than a project-level constraint.

The Explore → Plan → Implement → Commit Workflow

This four-phase workflow is the practical pattern for using Plan Mode on non-trivial tasks. It mirrors how experienced engineers approach complex changes: understand before acting, plan before building, build before shipping.

Phase 1: Explore

Before activating Plan Mode, give Claude time to explore the codebase. Point it at the relevant areas:

Read through the auth module, especially the token handling in src/auth/. 
I want to understand the current flow before we plan any changes.

Or use a subagent to keep the exploration out of your main context:

Use a subagent to explore how the payment module handles failed transactions.
Report back with a summary — file names, key functions, and the current error handling path.

This phase can happen in any permission mode. You are gathering context, not making changes.

Phase 2: Plan

Activate Plan Mode (via Shift+Tab, /plan prefix, or --permission-mode plan) and describe the task:

/plan

Refactor the token service to:
1. Support refresh token rotation (current implementation does not invalidate old tokens)
2. Add structured logging for all token operations
3. Keep the existing interface — callers should not need to change

Explore the codebase as needed before writing the plan.

Claude reads files, traces call paths, checks tests, and produces a plan. The plan will typically include:

• What files will change
• What the changes will be
• What tests need updating
• Risks and edge cases
• Sequence of operations

Phase 3: Review and Approve

When the plan is ready, Claude presents an approval dialog with options:

Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds. This lets you remove steps, add constraints, or reorder the sequence before execution starts.

If showClearContextOnPlanAccept is enabled in settings, each approval option also offers to clear the planning context before execution. This prevents the exploration phase from consuming context budget during implementation.

Phase 4: Implement

After approval, Claude implements the plan in the permission mode you selected. If you approved with “accept edits” mode, you can track progress through your editor’s diff view or with git diff after each batch of changes.

The plan document is saved to plansDirectory (default: ~/.claude/plans) for reference. You can check past plans to understand why specific decisions were made or to restart an interrupted implementation.

plansDirectory — The Underused Config

plansDirectory is a settings field that most developers ignore. It is more useful than it looks.

What It Controls

When Claude produces a plan in Plan Mode, it writes the plan to disk. plansDirectory sets where. The default is ~/.claude/plans, which is global and not version controlled.

Change it in .claude/settings.json:

{
  "plansDirectory": "./plans"
}

Why a Project-Local Directory Matters

Keeping plans in the project directory has three practical benefits:

Version control: git add plans/ includes planning artifacts alongside implementation. A future reviewer can see what Claude was trying to accomplish, not just the resulting diff.

Resumable implementation: If a session crashes mid-implementation, you can start a new session, read the plan from disk, and continue from where you left off. The plan gives Claude the full context without re-exploration.

Team sharing: In a shared repository, plans can be committed as PR artifacts or reviewed as part of the code review process. “Here is the plan I approved, here is the resulting diff” is a useful audit trail.

Recommended Configuration

{
  "plansDirectory": "./plans",
  "permissions": {
    "defaultMode": "plan"
  }
}

Add plans/ to .gitignore if you do not want planning artifacts committed, or create a plans/ directory and commit it if you do. Both are reasonable choices depending on your team’s preferences.

Decision Matrix — When to Use Plan Mode

The threshold to use Plan Mode: if a mistake would be annoying to reverse, plan first. If a mistake would be trivial to reverse (or is so simple it is unlikely), skip it.

5 Scenarios Where Plan Mode Pays Off Most

Scenario 1: Touching an Unfamiliar Codebase

You have just joined a project or picked up someone else’s code. You know what needs to change conceptually but not where to make the changes or what depends on what.

Plan Mode forces Claude to map the territory before acting. The plan gives you a concrete picture of what is involved before any files change — and it is often different from what you expected.

claude --permission-mode plan

I need to add rate limiting to all API endpoints. I have not worked in this codebase before.
Explore the routing layer and produce a plan for where to add rate limiting middleware.

Scenario 2: Large Refactors Across Many Files

Refactoring a module that other parts of the codebase import, changing an interface signature that has many callers, migrating from one library to another — these tasks have a high blast radius.

Plan Mode reveals the full scope before execution starts. The plan will list affected files, call sites, and test changes. You can catch “I did not realize this was used in 12 places” before any code has changed.

Scenario 3: Database Migration Design

Database migrations are among the highest-risk changes in most applications: they can lock tables, break the running application version, or be impossible to roll back safely.

Plan Mode is well-suited here. Ask Claude to plan the migration, review the plan for backward compatibility and rollback safety, then approve. The plan serves as a checklist for the actual migration procedure.

/plan

Design a migration to add a `deleted_at` column to the users table for soft deletes.
Consider: backward compatibility with the current app version, index impact, 
the down migration, and whether this needs a data migration step.

Scenario 4: Security-Sensitive Changes

Authentication changes, permission model updates, anything touching sensitive data — these warrant review before implementation. Plan Mode adds a mandatory checkpoint between “here is what I want” and “here is what changed.”

The plan will often surface security considerations you did not think to ask about: “This change makes token validation optional if the header is missing — is that intended?”

Scenario 5: Parallel Session Handoff

You are running parallel Claude Code sessions on different parts of a task. One session produces a plan; another session implements it.

# Session 1: Produce the plan
claude --permission-mode plan -p "Plan the API v2 migration for the user service"

# Session 2: Implement the plan
claude "Implement the plan at ./plans/api-v2-migration.md"

This pattern separates exploration from implementation cleanly and gives you a reviewable artifact between the two phases.

Common Mistakes and How to Avoid Them

Mistake 1: Confusing /plan with “Don’t Write Code Yet”

They look similar but behave differently. /plan activates a system-level permission mode that enforces the read-only constraint. “Don’t write code yet” is a conversational instruction that Claude follows as guidance but can drift away from across multiple turns.

The difference shows up on complex tasks. If you say “think before you act” and the task is a large refactor, Claude will often start making changes partway through — not because it is ignoring you, but because the task framing becomes dominant as it gets into the work. Plan Mode does not drift.

Rule: For anything you genuinely need to review before execution, use Plan Mode. For lightweight alignment on simple tasks, a conversational instruction is fine.

Mistake 2: Approving Without Reading the Plan

Plan Mode is only as useful as the review you do. If you approve the plan without reading it, you are adding latency with no benefit.

Read the plan with specific questions in mind:

• Are there files listed that should not change?
• Does the sequence of operations make sense? (Especially: does it migrate data before or after changing the schema?)
• Are there missing steps? (Tests, documentation, config changes?)
• Does the rollback path exist if implementation goes wrong?

Mistake 3: Not Using plansDirectory

The default ~/.claude/plans directory is global and ephemeral from the project’s perspective. You lose the plan context when you switch projects or machines.

Set plansDirectory to a project-local path for any project where you use Plan Mode regularly. The plans directory is lightweight and cheap to maintain.

Plan Mode + Subagents for Deep Investigation

Plan Mode’s explore phase can exhaust your context window on large codebases. The files Claude reads stay in context, and a thorough exploration of a 100k-line codebase can fill most of the available context before you even start planning.

The fix: use a subagent for exploration so the file reads happen in the subagent’s context, and only the findings return to your main session.

Use a subagent to explore the auth module:
- Map all files and their dependencies
- Identify every call site for the TokenService
- Note any tests that cover token operations
- Return a summary: file list, dependency graph, test coverage gaps

After the subagent reports back, enter plan mode and produce a refactoring plan.

The subagent handles the exploration in its own context. Your main session receives the summary — a fraction of the token cost. Then you activate Plan Mode and plan from the summary rather than from thousands of lines of file content.

The built-in Explore agent is optimized for this pattern: it runs in a lean context that skips CLAUDE.md and git status, reads with targeted tools, and returns focused findings.

FAQ

Q: Does Plan Mode work the same in VS Code and the desktop app as in the CLI?

Yes. The permission modes are consistent across surfaces. In VS Code, click the mode indicator at the bottom of the prompt box to switch to Plan Mode. In the desktop app, use the mode selector next to the send button. The underlying constraint — read-only, no file edits — is identical.

Q: Can I use Plan Mode in CI pipelines?

Yes. Use --permission-mode plan with -p for non-interactive execution:

claude -p --permission-mode plan "Analyze the current test coverage gaps in src/auth/"

Claude explores, produces the plan, and outputs it to stdout. No approval dialog. Useful for generating planning artifacts as part of a review workflow.

Q: What happens if I press Ctrl+C while Claude is in the planning phase?

The session is interrupted. Any partial plan that was written to plansDirectory may or may not be complete, depending on when you interrupted. Resume with claude --continue to pick up the session, or start fresh.

Q: Does Plan Mode cost more tokens?

The exploration phase reads files and runs commands, which uses tokens. You are essentially paying for two passes: exploration plus planning, then implementation. For complex tasks where the planning prevents a wrong implementation, this is almost always worth it. For simple tasks, the overhead is not justified.

Q: What is Ultraplan and when should I use it instead of local Plan Mode?

Ultraplan routes the planning task to a Claude Code on the web session and gives you a browser-based review interface: inline commenting on specific sections, emoji reactions, and a document outline sidebar. Use it when you want richer feedback tooling than the terminal allows, when you are collaborating with someone who needs to review the plan, or when you want the plan generated in the cloud while you keep your terminal free. It requires Claude Code v2.1.91+.

Q: Can Plan Mode be set per-directory so different subdirectories have different defaults?

defaultMode in .claude/settings.json applies to the project root and all subdirectories. There is no per-subdirectory mode override. If you want different behavior in a subdirectory, start Claude from that subdirectory with --permission-mode specified at startup.

Related Resources

• Using Claude Code Plan Mode to Design Better CLAUDE.md Files — A specific workflow for using Plan Mode to audit and design CLAUDE.md
• Claude Code Best Practices: CLAUDE.md Design (2026) — How to write CLAUDE.md that works well with planning workflows
• Claude Code Subagents: Best Practices (2026) — Using subagents to handle exploration without burning main context
• Writing Effective CLAUDE.md for 2026 — Pairing persistent instructions with Plan Mode for better outcomes