Get Claude's Plan Before It Touches a File: Plan Mode and --permission-mode plan

TL;DR: Plan Mode is a hard read-only sandbox in Claude Code — Claude reads, explores, and writes a plan, but cannot edit a single file until you explicitly approve.

Every destructive bug from an AI coding session happened because the agent started editing before you understood what it intended. Plan Mode enforces a mandatory planning phase: Claude reads files, runs read-only shell commands, and produces a step-by-step change plan — but write tools are physically disabled until you approve.

Three ways to enter Plan Mode

1. Keyboard toggle: Press Shift+Tab at any point in a session. Claude immediately stops editing and switches to plan-only mode. Press Shift+Tab again to resume action mode.

2. Slash command: Prefix any prompt with /plan:

/plan refactor the auth module to use OAuth 2.0 — list every file you'll touch

Claude produces a plan for that specific task and waits. Nothing runs until you respond with approval.

3. CLI flag — best for CI and scripted workflows:

claude --print --permission-mode plan "migrate users table to add stripe_customer_id"

Claude reads your codebase, thinks through the migration, and prints a detailed plan — then exits without touching a file. Pipe it to a review step or attach it as a PR comment:

claude --print --permission-mode plan "describe changes needed for GDPR compliance" \
  | gh pr comment $PR_NUMBER --body-file -

What's enforced

• Edit, Write, and file-modifying Bash commands are blocked — not soft-blocked, physically unavailable
• Read-only tools (Read, Grep, Glob, WebSearch) work normally
• Shell commands that modify files (including touch, rm) still prompt for approval even in plan mode
• With useAutoModeDuringPlan on (the default), auto mode approves read-only commands silently so Claude can explore freely without permission spam

When to reach for it

• Before any risky change: database migrations, file deletions, auth refactors
• At session start for unfamiliar codebases — see what Claude thinks it needs to change before it acts
• In CI as a dry-run gate: plan step in one job, apply in another (gated on human approval)

Sources: Claude Code: Permission modes (official) · Common workflows · Plan Mode guide (2026)