---
name: plan-mode-reference
description: CC plan mode — read-only planning phase before implementation, with explicit user approval gate.
layer: reference
cc_feature: plan-mode
source: https://docs.claude.com/en/docs/claude-code/plan-mode
concept: planning-before-execution
last_verified: 2026-04-18
ngram_overlap_score: null
review_status: approved
---

# Plan Mode — Reference

Plan mode is a built-in state where Claude operates read-only and
produces an implementation plan instead of executing it. The user
reviews the plan, then either approves it to transition to
implementation or iterates.

## State machine

1. **Plan mode entered** — user triggers it (Shift+Tab twice, `/plan`,
   or harness-initiated) or Claude calls `EnterPlanMode`.
2. **Read-only operation** — Claude can read files, search, run
   analysis. Writes, edits, and commits are blocked by the harness.
3. **Plan produced** — Claude presents a plan via `ExitPlanMode` or
   equivalent.
4. **User reviews** — accepts, rejects, or iterates.
5. **Exit** — on acceptance, mode returns to normal (edits allowed).

## What plan mode guarantees

- No writes during the plan phase. Even if Claude tries, the harness
  denies write tools.
- A structured handoff: the plan is a message the user sees before
  anything happens.

## What plan mode does not guarantee

- Plan quality. Plan mode is a *gate*, not a *reviewer*. A bad plan
  still passes if the user approves it.
- Scope locking. After exit, Claude can do whatever the new prompts
  ask — plan mode is a phase, not a contract.

## When to opt into plan mode

- Tasks touching multiple files or modules where the order and file
  list matter.
- Refactors where the first wrong edit is expensive to undo.
- Unfamiliar codebases where planning surfaces missing context.

## When to skip plan mode

- Single-file trivial changes.
- Tasks already specified by a detailed plan from another tool
  (e.g., an `ultraplan-local` plan.md) — planning twice is waste.

## Relationship to /ultra* planning

- `/ultraplan-local` produces a *plan artifact* that outlives the
  session. Plan mode produces an *in-conversation plan* that does not
  survive `/clear`.
- They compose: use plan mode to sketch at session start, then run
  `/ultraplan-local` to get the durable, reviewable, machine-readable
  plan with manifests.