Claude Code Plan Mode: Think First, Code Second (Complete Guide)

What Plan Mode Does

Plan mode splits Claude Code into two phases. In the first phase, Claude reads files and reasons about your request. It cannot edit files, run commands, or use any tools. In the second phase, after you approve its plan, it executes with full tool access.

The output of phase 1 is a structured plan: which files to edit, what changes to make, in what order, and why. You review it and choose one of three responses:

How to Activate Plan Mode

Three ways to enter plan mode, depending on whether you want it for one turn, one session, or every session.

# Plan mode for this session
claude --plan

# Plan mode + autoaccept (power-user workflow)
claude --plan --auto-accept

# Plan mode for a specific task
claude --plan "Refactor the auth module to use JWT tokens"

The Think-Then-Execute Workflow

Plan mode is not a separate feature. It is a phase. The workflow looks like this:

You: "Refactor the payment module to support multiple currencies"

[Plan Mode - Phase 1]
Claude reads: src/lib/payments.ts, src/types/order.ts,
              src/api/checkout.ts, tests/payments.test.ts

Claude proposes:
1. Add Currency type to src/types/order.ts
2. Update PaymentService in src/lib/payments.ts
   - Add currency parameter to processPayment()
   - Add exchange rate lookup via existing ExchangeAPI
3. Update checkout API to accept currency from frontend
4. Add 12 test cases covering USD, EUR, GBP conversions

You: "Looks good, but use a separate exchange-rates.ts file"

[Phase 2 - Execution]
Claude creates src/lib/exchange-rates.ts
Claude updates src/lib/payments.ts
Claude updates src/api/checkout.ts
Claude adds tests

When to Use Plan Mode

Plan mode adds value when the cost of a wrong first step is high. Three scenarios where it consistently outperforms direct execution:

When to Skip Plan Mode

Plan mode adds one turn of overhead. For small, obvious tasks, this overhead is not worth it. Skip plan mode when:

• You could describe the exact edit in one sentence
• The change touches a single file
• You are fixing a typo, adding a log statement, or updating a constant
• You have already told Claude exactly what to do and where

The rule of thumb: if Claude does not need to discover anything before acting, plan mode wastes tokens.

Plan Mode + Autoaccept

The power-user workflow combines strategic oversight with execution speed. Plan mode for strategy, autoaccept for execution.

# Start with both flags
claude --plan --auto-accept

# Claude will:
# 1. Read files and propose a plan (you review)
# 2. After you approve, execute WITHOUT asking
#    permission for each file edit or bash command
# 3. Return to plan mode for the next prompt

This workflow gives you one decision point (approve/reject the plan) instead of dozens (approve each tool use). For experienced developers who trust Claude's execution but want oversight on strategy, this is the optimal balance.

Plan Mode with Agent Teams

For agent teams, plan mode becomes a coordination tool. The team lead agent uses plan mode to create a strategy, then delegates specific parts of the plan to subagents.

Team Lead (plan mode):
  "Add OAuth2 support to the API"

  Plan:
  1. Agent A: Add OAuth2 middleware to src/middleware/
  2. Agent B: Update user model with OAuth fields
  3. Agent C: Write integration tests
  4. After A+B complete: Agent D updates API docs

Each subagent gets only its part of the plan.
Total context: 4 × 30K = 120K tokens
Without teams: 1 × 300K+ tokens

Each subagent reads only the files its part of the plan requires. This reduces total token usage compared to a single session that accumulates the entire codebase context. See Claude Code cost optimization for the full cost breakdown.

FAQ