Contents
What is Plan Mode?
Plan Mode is Claude Code's "think before you leap" feature. In normal mode, Claude reads your request and immediately starts editing files. In Plan Mode, it pauses at a planning step — producing a structured list of every action it intends to take — and waits for your go-ahead.
This gives you a chance to catch misunderstandings early, redirect the approach, or simply verify Claude understood the scope of work before irreversible changes pile up.
How to Activate Plan Mode
In the interactive REPL
Toggle Plan Mode on/off with a single keyboard shortcut:
When active, a 📋 Plan Mode indicator appears in the prompt. Press the same keys again to switch back to ⚡ Normal.
Via slash command
/plan
Type /plan at the Claude Code prompt to enter Plan Mode for your current request. This is useful when you've already typed a message and want to make it planning-only without reaching for the keyboard shortcut.
Scope
Plan Mode is sticky — it stays on until you toggle it off. You can also enable it per-message with the slash command without changing the default for subsequent messages.
Plan Mode Workflow Walkthrough
- Toggle Plan Mode on with Shift+Tab. The prompt indicator changes.
- Describe your task as you normally would: "Refactor the auth module to use JWT instead of sessions, update all tests, and remove the old session middleware."
- Claude presents the plan — a numbered list of files to read, files to edit, new files to create, and the order of operations. No code is written yet.
- Review and respond. You can approve it, modify it, or redirect: "Skip the test updates for now" or "Also check src/middleware/rate-limit.ts".
- Claude revises if needed and re-presents the updated plan.
- Approve by typing
proceedor pressing Enter. Claude executes the plan exactly as presented.
"Here's my plan:
1. Read package.json and prisma/schema.prisma to understand current setup.
2. Install drizzle-orm and drizzle-kit, remove @prisma/client.
3. Create src/db/schema.ts mirroring the Prisma schema.
4. Rewrite src/db/client.ts to use Drizzle's connection pool.
5. Update 12 query files in src/repositories/ (list them here).
6. Remove src/prisma/ directory.
7. Update drizzle.config.ts and run migrations.
Shall I proceed?"
Plan Mode vs Normal Mode
Plan Mode
- Claude plans before acting
- Full list of affected files shown upfront
- You can redirect before any edits
- Slower per-task (extra round-trip)
- Best for complex, multi-file changes
- Reduces "oops" moments on risky refactors
- Useful for new codebases you don't know well
Normal Mode
- Claude reads and acts immediately
- Faster for targeted, scoped tasks
- No extra approval step
- Best for small, well-scoped edits
- Good when you trust Claude's interpretation
- Less friction for exploratory sessions
- Works well with git safety net (commit first)
When to Use Plan Mode
Always use Plan Mode for:
- Database migrations — schema changes that can't be rolled back easily
- Major refactors — moving from one architecture/pattern to another
- Security-critical changes — auth, permissions, input validation rewrites
- Dependency upgrades — e.g. major version bumps that change APIs
- Unfamiliar codebases — when you haven't mapped the blast radius yet
- Cross-service changes — touching both frontend and backend contracts
Skip Plan Mode for:
- Adding a single function or component
- Fixing a specific, isolated bug
- Writing tests for a file you just reviewed
- Renaming a variable or adjusting formatting
- Exploratory "explain this code" sessions
Power-User Tips
Combine with a pre-task git commit
Before any complex task, commit your current work: claude /commit. Even with Plan Mode, having a clean rollback point is good practice.
git stash # or: claude /commit
# toggle Plan Mode
# give Claude your task
# review plan, approve
# verify changes with git diffAsk Claude to explain its reasoning
When reviewing a plan, type "why step 4?" to get Claude to explain its reasoning before you commit. This catches misunderstandings without starting over.
Narrow scope during plan review
If the plan touches files you don't want changed: "Don't touch src/legacy/ — treat it as read-only". Claude revises accordingly.
Add steps the plan missed
"Also update the OpenAPI spec in api/openapi.yaml" — Claude appends the step and re-presents. Cheaper than reviewing a diff of a file you forgot about.
Save a plan as a task list
When Claude presents a long plan, ask "write this plan to TASKS.md". You can then track progress per-file and resume if the session is interrupted.
# After plan approval:
"Write the plan to TASKS.md and mark each file complete as you go"Use Plan Mode during code review prep
Before a PR, enter Plan Mode and ask: "What would you change to make this PR reviewable — add missing tests, fix style issues, update docs?" Claude returns a changelist you can approve selectively.
Plan Mode in Headless / CI Use
Plan Mode's interactive approval step makes it unsuitable for fully automated claude -p pipelines. You can still get the planning benefit by structuring your system prompt:
claude -p "$(cat <<'EOF'
You are a code refactoring assistant.
IMPORTANT: Before making any file edits, output a numbered list of
every file you intend to change and WHY. Format it as:
PLAN:
1. [filename] — reason
2. ...
Then output EXECUTING PLAN and make the changes.
EOF
)" "Migrate our Express.js routes to use async/await"See also: Claude Code Headless Mode and CI/CD Integration Guide.
FAQ
How do I enable Plan Mode in Claude Code?
Press Shift+Tab in the interactive Claude Code session. A plan indicator appears in the prompt. Toggle again to exit. You can also type /plan before your message.
What is Claude Code Plan Mode?
Plan Mode pauses Claude before it takes any action — it first presents a structured list of every file it will read, create, or modify, and waits for your approval. This prevents surprises on complex, multi-file tasks.
Can I use Plan Mode in headless / CLI mode?
Plan Mode's interactive approval is only available in the REPL. For claude -p pipelines, embed a planning instruction in your system prompt to get a plan log, but without the approval gate.
When should I use Plan Mode vs normal mode?
Use Plan Mode for any task touching more than 3 files, migrations, security changes, or unfamiliar codebases. Use normal mode for quick, scoped edits where you trust Claude's interpretation.
Does Plan Mode work with extended thinking?
Yes. In Plan Mode, Claude uses extended reasoning to map dependencies and edge cases before presenting the plan, often producing more thorough and accurate step lists than in normal mode.
How do I modify or reject a plan?
Reply in natural language: "skip step 3", "also update the tests", "don't touch the database layer". Claude revises and re-presents. Type proceed or press Enter to approve and execute.
Related Guides
Master every Claude Code feature
Browse the full reference — commands, shortcuts, workflows, and comparisons.
← Back to all guides