Claude Code Plan Mode
Plan mode is Claude Code's "think before you act" gear. When you prefix a request with /plan, Claude produces a complete implementation proposal — files to create, steps to execute, dependencies to install — without touching a single file. You review, refine, and approve. Only then does Claude begin making changes.
For complex or risky changes, this single round-trip prevents broken states, avoids unwanted scope creep, and lets you redirect before any work is done.
How Plan Mode Works
- You type
/planfollowed by your request: /plan Add rate limiting to all API endpoints - Claude reads the codebase (file reads and searches are allowed in plan mode) but writes nothing
- Claude returns a structured plan: ordered steps, affected files, trade-offs, and any decisions requiring human input
- You review the plan and either approve, refine, or reject it
- On approval, Claude exits plan mode and executes — in the same order it described
The hard guarantee: In plan mode, the Edit, Write, and Bash tools are blocked. Claude cannot write, delete, or execute shell commands. You see exactly what will happen before anything does.
Triggering Plan Mode
The /plan slash command (interactive)
In the interactive Claude Code CLI, prefix your message:
/plan Refactor the auth middleware to support both JWT and API key strategiesClaude enters plan mode, presents the proposal, then waits for your response.
Claude-initiated plan mode
For sufficiently complex tasks, Claude may enter plan mode automatically even without /plan. You'll see it call EnterPlanMode in the tool call stream. The behavior is identical — Claude is still waiting for your approval before writing anything.
Plan sub-agent (SDK / headless)
In non-interactive SDK usage, spawn a dedicated Plan agent:
Agent({
subagent_type: "Plan",
description: "Design auth refactor",
prompt: "Design a plan to refactor auth middleware to support JWT + API key strategies. Identify the affected files, step ordering, and any risks. Return the plan as a numbered list."
})The Plan agent cannot write files. Its returned text becomes the plan your orchestrator reviews before dispatching write agents.
Reviewing and Approving a Plan
Approve as-is
Looks good, go ahead.
# or: "yes", "approved", "execute", "do it"Refine before approving
Skip step 3 — the DB migration already ran in staging.
Also handle the case where the user object is null in step 5.
Then proceed.Claude revises the plan and presents a new version. You can iterate through multiple revisions at no execution cost.
Reject entirely
Cancel — I want a different approach.
Instead of middleware, let's use a decorator pattern at the route level.What a Good Plan Looks Like
A complete plan should contain all of these:
Why this approach over alternatives. Trade-offs stated explicitly.
Each step names the specific file(s) and change type: create / edit / delete.
Any packages to install, env vars needed, or services that must be running.
The test command or manual check that confirms success at the end.
Steps that can't easily be undone (schema migrations, force-pushes) are called out explicitly.
Any step where Claude needs your input before it can proceed safely.
If a plan is missing any of these, ask Claude to expand it before approving: "Add a verification step" or "What are the alternatives you considered?"
Common Plan Mode Patterns
Large feature implementation
/plan Implement real-time notifications using WebSockets.
Include: backend event emitter, client-side connection, reconnect logic, and fallback to polling.Claude maps out the full implementation across backend and frontend files before touching anything.
Risky refactors
/plan Migrate all API routes from Express callbacks to async/await with centralized error handling.You see every file that will be modified. If the list is longer than expected, you can narrow scope before any changes happen.
Dependency upgrades
/plan Upgrade from React 18 to React 19. Identify breaking changes in our codebase and propose a migration path.Claude reads the codebase for React 18-specific APIs, checks for breaking patterns, and drafts a phased upgrade plan you can schedule across multiple sessions.
Multi-agent design
/plan Design the agent architecture for an automated PR review pipeline.
Inputs: a GitHub PR URL. Outputs: inline comments + a summary verdict.Claude produces an agent-graph diagram (as text/ASCII), identifies which sub-agent types to use, and specifies the handoff contract between agents.
Plan Mode vs. "Just Think First"
| Approach | Tool writes blocked? | Requires approval? | Best for |
|---|---|---|---|
| Ask Claude to "describe what you'll do" | No | No | Understanding an approach; may still read files while describing |
/plan (plan mode) |
Yes | Yes | Risky/complex changes where an early wrong write costs time |
| Plan sub-agent (SDK) | Yes | Programmatic | Headless pipelines; orchestrator reviews before dispatching write agents |
Best Practices
- Give context upfront. The richer your
/planprompt (constraints, related files, what NOT to change), the more accurate the first plan will be. - Check the file list. If step 2 modifies 40 files but you expected 4, ask why before approving. Scope creep is easier to prevent than revert.
- Name the verification step. If the plan doesn't include a "run tests" or "curl the endpoint" step, add one in your approval message.
- Use plan mode at the start of a session. Once you've approved a plan, Claude will follow it even across multi-step sessions — it won't silently deviate unless you ask it to.
- Don't plan-gate small tasks. A one-line fix doesn't need a plan. The round-trip overhead only pays off when the risk of a wrong first move is real.
FAQ
Can I see the plan mode output in the Claude Code UI?
Yes. In the interactive CLI, Claude's plan appears as normal text output. In the desktop/web app, plan mode tool calls (EnterPlanMode / ExitPlanMode) may appear as collapsible tool call blocks. The plan text is always readable in the main conversation stream.
Does /plan work for shell commands too, or only file edits?
Plan mode blocks all execution — file writes AND shell commands. If a plan step says "run npm install" or "run db migration", Claude will list it as a step but not run it until you approve.
What if Claude exits plan mode without my approval?
In the interactive CLI, Claude waits for your text response before exiting plan mode — it cannot self-approve. In SDK usage where you control the conversation loop, you handle ExitPlanMode tool calls in your code; if you automatically continue without checking, the plan is effectively auto-approved. Build an approval gate into your SDK loop for untrusted tasks.
Is plan mode the same as Claude Code's "extended thinking"?
Different mechanisms, complementary purposes. Extended thinking (available on Claude Opus/Sonnet 3.7+) is an internal chain-of-thought process that improves reasoning quality — it runs before Claude produces any output and is not user-visible. Plan mode is an explicit tool-call boundary enforced by the harness; it's about workflow control (no writes until approved), not about the quality of reasoning. You can have plan mode active while extended thinking is also enabled.
Can I save plans between sessions?
Claude doesn't persist plans across sessions automatically. If you want a saved plan: ask Claude to write the plan as a PLAN.md file before approving, then reference that file in future sessions. Alternatively, use a CLAUDE.md file to capture the architectural decisions from the plan so future sessions have the context.
How does plan mode interact with Claude Code hooks?
Hooks still fire during plan mode for any tool calls that ARE allowed (Bash reads, file reads). But hooks attached to Edit or Write events will not fire during plan mode because those tool calls are blocked. If you have a pre-write hook for validation, it will fire during execution (after plan approval) as expected. See the hooks guide for full event reference.
Related Guides
- Sub-Agents & Orchestration — spawn parallel Plan + write agents for complex pipelines
- Claude Code Hooks — event-triggered automation around plan approval and execution
- Best Practices — CLAUDE.md, permissions, and context management
- Memory & CLAUDE.md — persist decisions from plans across sessions
- Permissions & Safety — how Claude Code restricts what it can change
- All Claude Code Skills — full directory