Claude Code Plan Mode

Quick Answer

Plan mode makes Claude Code describe every action before running it. Toggle with Shift+Tab once from default mode, or start with the --plan flag. You see the list of proposed tool calls, approve individual steps or the whole plan, and redirect if the approach is wrong. TLDR: turn it on for risky operations, unfamiliar code, and production changes, then turn it off for quick tasks where you already trust the agent.

Summary of the 7 things plan mode does

1. Prints the proposed action list before any tool call
2. Pauses for approval on each step
3. Lets you redirect mid-plan if the approach is wrong
4. Shows the reasoning behind each proposed tool call
5. Makes audits and code reviews predictable
6. Costs the same tokens as default mode
7. Toggles back to default or auto-accept with Shift+Tab

What plan mode actually is

Claude Code runs in one of 3 permission modes. Default prompts for approval on every write and every shell command. Plan mode goes further: Claude describes the full action list first, you approve the plan, then execution proceeds step by step with per-step approval too. Auto-accept mode runs everything with no prompts.

Plan mode sits between default and auto-accept in terms of friction. It adds one extra approval step (the plan itself) but gives you a clear view of what Claude intends to do. For risky or unfamiliar work, that view pays for itself.

How to enable plan mode

Two ways. From an active session, press Shift+Tab once to cycle into plan mode. Press again to cycle into auto-accept. Press a third time to return to default.

From the command line, start the session with the --plan flag. This drops you directly into plan mode and skips the cycle.

You can also configure plan mode as the default in .claude/settings.json by setting the permissionMode field to plan. Projects that do a lot of risky work often do this.

What you see in plan mode

After you send a prompt, Claude prints a numbered list of proposed tool calls before executing any of them. A typical plan for a small feature might look like this.

1. Read package.json to find the test command
2. Read src/routes/settings.tsx to understand current structure
3. Edit src/routes/settings.tsx to add the new section
4. Run pnpm test to verify no regressions
5. Commit with a conventional message

Each step includes the arguments Claude intends to pass. For edits, the proposed old and new strings are visible. For shell commands, the full command is printed. For reads, the file path is named.

You then approve the full plan, approve step by step, or reject and redirect.

When plan mode is valuable

Plan mode earns its keep in 4 scenarios.

First, production changes. Anything touching a deployed system, a DB migration, a shared config file, or CI pipelines benefits from seeing the full sequence before action. Catching a wrong migration at step 1 is 100x cheaper than catching it after it runs.

Second, unfamiliar codebases. When you start work on a new repo, plan mode lets you verify that Claude understood the architecture before it edits anything. A plan that reads the wrong files is a clear signal to refine the prompt or add to CLAUDE.md.

Third, destructive operations. Any task involving delete, rm, drop, force-push, or reset is a candidate for plan mode. You want to see the command before it runs.

Fourth, code reviews and audits. When using Claude Code to audit a codebase (checking for security issues, dead code, or pattern violations), plan mode shows which files it will read and lets you verify coverage before spending tokens on output.

The approval flow

Plan mode approval works at 2 levels. Plan-level approval accepts the full sequence up front and runs without further prompts. Step-level approval accepts each tool call individually.

In practice, most users default to step-level approval for the first few steps, then hit accept-all when they see the plan going the right direction. This catches misdirections early without forcing you to click through 20 approvals.

Rejection gives you 2 options. Reject and redirect (Claude regenerates the plan with your new guidance). Reject and stop (session pauses, you retype your next prompt).

Editing plans mid-stream

Plans are not locked in. If step 3 reveals something unexpected (a file that is not what Claude assumed, a test that fails), Claude pauses and asks what to do. You can let it replan, manually specify the next step, or stop the session.

This mid-plan flexibility is what makes plan mode valuable for exploratory work. The agent commits to a direction but respects the reality it discovers.

A concrete example. You ask Claude to refactor a module. The plan has 6 steps. At step 2, Claude reads the module and finds it is 10x larger than expected. It pauses: continue with the original plan, split into smaller subtasks, or stop and rescope. You pick split, and the plan regenerates with a safer sequence.

Combining plan mode with CLAUDE.md rules

A well-tuned CLAUDE.md sets expectations for how Claude approaches work. Plan mode surfaces whether Claude is following those rules. If the plan violates your rules (say, editing a file outside the allowed folder), you see it before the edit happens.

This combination makes onboarding safer. Claude has the rules. You verify the rules are respected. Mistakes surface at planning time, not at commit time.

Plan mode vs default vs auto-accept

The 3 modes form a spectrum from careful to fast.

Default mode: approval per tool call, no upfront plan. Good for most work. You see each action as it happens. Slower than auto-accept, safer than it.

Plan mode: full plan up front, approval per step. Good for risky and unfamiliar work. Slower than default because of the planning overhead, but much safer on high-stakes tasks.

Auto-accept mode: no prompts, Claude runs end to end. Fastest and riskiest. Good for well-defined tasks in clean codebases with reliable tests and hooks.

A practical default is to start in default mode, toggle to plan mode when you touch risky files, and toggle to auto-accept only in an isolated worktree where nothing can break the main branch.

Cost in plan mode

Plan mode costs the same tokens as default mode. The planning step is just extra output tokens up front, which cost roughly 5 to 15 cents on Sonnet for a typical plan. That cost pays for itself the first time the plan reveals a wrong approach before execution.

There is no hidden premium for plan mode. The safety comes from slower approval, not a more expensive model or extra compute.

Using plan mode for teaching

One useful side effect of plan mode is teaching. When a junior developer watches Claude produce a plan, they see the implicit steps they would take for the same task. The plan is essentially a written-out approach that normally lives in a senior developer head.

Teams using Claude Code for onboarding often run new hires in plan mode for the first 2 weeks, then relax to default mode as trust builds.

Team audits with plan mode

For code review audits, run Claude in plan mode with a read-only settings file (no Write or Edit tools enabled). Ask Claude to audit for a specific pattern (security issues, accessibility violations, dead exports). The plan shows which files will be read. You verify coverage, approve, and let the audit run.

The resulting audit is reproducible because the plan is visible. Team members can re-run the same audit against new code and expect similar behavior.

When not to use plan mode

Plan mode is overkill for tasks with 1 or 2 steps. If you are asking Claude to write a 3-line function or format a file, the planning overhead costs more than the value it provides.

It is also overkill for repeat workflows you have run many times. Once you trust the pattern, drop back to default or auto-accept for speed.

The sweet spot is tasks with 4 to 15 steps in an area where mistakes are expensive. For those, plan mode is worth every second.