Plan Mode

Hold the agent to read-only until you've seen its plan — so you correct the approach in a paragraph, not in a broken diff.

Why this, for you: you've watched an agent confidently write the wrong thing — wrong files, wrong pattern, scope it invented on the way. By the time you saw it, the cost was already paid in context, tokens, and git revert. Plan Mode moves that correction upstream, to the cheapest moment.

Plan Mode is a permission mode in Claude Code that blocks all file writes and state-changing shell commands. The agent can read files, search code, and analyze the codebase — but it cannot modify anything. That one constraint separates understanding from implementation.

1 Why a read-only gate pays for itself

The economics are lopsided, and that's the whole point:

Fixing a plan costs minutes. Fixing an implementation costs context, tokens, and git reverts. Plan Mode makes the agent's understanding of the task visible before it acts on it.

If the agent targets the wrong files, misreads the architecture, or picks an approach that conflicts with existing patterns, you see that in the plan — not in a diff you now have to unwind. And because writes are blocked, the read-only constraint forces the agent to ask questions (via AskUserQuestion) and propose steps rather than run them. You review, correct, and approve before anything changes on disk.

2 Activate it, then run the four phases

There's more than one way in, depending on whether you're mid-session or starting fresh:

Method	Command
During a session	`Shift+Tab` (cycles Normal → Auto-Accept → Plan)
New session	`claude --permission-mode plan`
Headless query	`claude --permission-mode plan -p "Analyze the auth system"`
Default for project	`"defaultMode": "plan"` in `.claude/settings.json`

The status bar shows that plan mode is active while it's in effect. From there the loop has four phases:

Explore (Plan Mode) — the agent reads the codebase and maps the relevant files, functions, and dependencies.
Plan (Plan Mode) — it proposes a step-by-step approach. Press Ctrl+G to open the plan in your editor and edit it directly.
Implement (Normal Mode) — switch out of Plan Mode; the agent works against the reviewed plan.
Verify — run tests, review the diff, check for regressions. Issues found loop you back to Plan.

Review the plan, don't rubber-stamp it

Before approving, check five things: the agent identified the correct files, the approach matches existing patterns, there's no scope creep beyond the task, edge cases and error handling are addressed, and the plan accounts for tests. When you accept, Claude names the session from the plan content — which helps when you resume later.

3 When to reach for it — and when to skip

Plan Mode is overhead. It earns that overhead when the cost of a wrong approach is high, and wastes it when the path is obvious. Match the tool to the task:

Use Plan Mode	Skip Plan Mode
Multi-file changes with cross-file dependencies	Single-file, well-defined edits ("add a null check to line 42")
Unfamiliar codebases where bad assumptions are likely	Tasks where the implementation path is obvious from context
Multiple valid approaches where you choose the direction	Quick fixes where planning overhead exceeds a bad attempt
Refactoring where scope needs explicit boundaries

The anti-pattern: telling an agent "just implement it" on a multi-file feature. It picks the first viable approach — which may conflict with existing patterns, miss shared utilities, or duplicate code. The rework costs more than the 30-second plan review would have.

# Start a headless, read-only exploration — no writes possible claude --permission-mode plan -p "Map the auth system: which files, which middleware, where sessions are stored. Propose a plan to add refresh-token rotation. Do not write anything yet." # Review the plan → switch to Normal Mode → implement → verify

↪ Your win: correct cheap, then build

Gate writes before you understand — Plan Mode blocks file writes and state-changing commands so exploration can't drift into action.
Make reasoning visible — wrong files or a clashing approach show up in the plan, not in a diff you have to revert.
Run the four phases — Explore → Plan → Implement → Verify, switching to Normal Mode only at implement.
Review against the checklist — correct files, matching patterns, no scope creep, edge cases, tests.
Skip it when the path is obvious — a single-line fix doesn't need a 30-second plan review.

Retrieval practice — recall, don't peek

Question 1While Plan Mode is active, the agent is allowed to…

Question 2The core economic argument for Plan Mode is that…

Question 3In the four-phase loop, you leave Plan Mode for Normal Mode at the…

Question 4Which task is the best fit for skipping Plan Mode?

Question 5Before approving a plan, the review checklist asks you to confirm the agent…

Ask me anything. Want a Plan Mode prompt tuned to a real refactor of yours, or help deciding which tasks are worth the planning overhead? Next in Part 1: Sub-Agents & Agent Teams — delegating bounded work so your main context stays clean.