Claude Code Plan Mode

The useful moment is the one before approval: you notice a missing caller, preserve an existing contract, or remove an unnecessary database change. A detailed plan earns its place by changing a decision.

What Plan Mode Does Today

Plan Mode asks Claude to investigate your codebase and propose changes. It can read files, run commands to explore, and write the plan. Ordinarily, source edits remain blocked until you approve. Think of it as reviewing renovation drawings before the builder starts moving walls. Anthropic’s planning workflow.

There is an important documented exception: in an interactive terminal session with bypass permissions available, Plan Mode’s blocks are not enforced. Claude is still instructed to plan, but an attempted edit can run. This includes making bypass available with --allow-dangerously-skip-permissions, even without selecting it as the active mode. If your purpose is to hold source edits behind approval, start without bypass enabled. Anthropic’s permission-mode rules.

The planning workflow and the permission system work together. The plan describes what Claude intends to change; the permission mode controls which actions can proceed without asking you.

Enter and Leave Plan Mode

In a terminal, start directly in Plan Mode:

claude --permission-mode plan

For a running session, use the controls below. Watch the mode indicator instead of relying on a fixed number of keypresses.

From auto, the cycle goes to default (Manual), then acceptEdits, then plan. Available optional modes follow: bypass permissions first, auto last. On Windows, Anthropic documents Alt+M as the alternative when the Node or Bun runtime does not enable VT input mode. Mode switching, keyboard reference, command reference.

When Claude presents a plan, the approval prompt lets you:

• Choose No, keep planning and give specific corrections.
• Choose Yes, manually approve edits to approve the approach while reviewing edits individually.
• Choose Yes, and use auto mode to approve and continue in auto mode, when available.

If auto mode is unavailable, the automatic option instead accepts edits automatically. If the session started with bypass enabled, that option switches to bypass permissions. Read the offered mode before selecting it. Approving exits Plan Mode and starts implementation under the selected permissions. Switching with Shift+Tab also leaves planning, but does not approve the proposed plan. Plan approval behavior.

Using an editor interface? In VS Code, click the mode indicator below the prompt and select Plan. In Desktop’s Code tab, use the mode selector beside Send. JetBrains uses the CLI controls inside its terminal. The changelog also records typed /plan support in VS Code from v2.1.280. Interface controls, official changelog.

Settings Worth Knowing

To start a project’s terminal sessions in Plan Mode, merge this into .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Use ~/.claude/settings.json for your user-wide terminal default instead. The launch flag takes precedence over settings, and project or managed settings can override your user default. VS Code has its own startup setting: set "claudeCode.initialPermissionMode": "plan" in VS Code user settings. The extension does not read project settings for its starting permission mode. Starting-mode configuration.

These additional keys sit at the top level of Claude Code settings, outside permissions:

These are separate choices: where a plan is saved, how commands are reviewed during planning, and whether an approval option clears the conversation. Settings reference, plan storage, clear-context option.

If you choose to clear context, put the constraints, unresolved decisions and acceptance criteria in the plan itself. Otherwise you are relying on discussion that implementation will no longer have.

How Plan Mode Fits With Auto Mode

Plan Mode holds the implementation decision for review. Auto mode reduces routine permission prompts by having a separate classifier model evaluate actions. A classifier checks an action against permission concerns; your plan review checks whether the proposed design solves the right problem.

When auto mode is available and useAutoModeDuringPlan remains enabled, that classifier also reviews shell commands during planning. Approved commands run; rejected commands are blocked. Without auto availability, or with that setting disabled, commands outside the built-in read-only set prompt instead. Critical-path removals have separate handling, and the interactive-terminal bypass exception takes priority. Planning does not mean that every shell command is read-only. Commands during planning.

For implementation, default means Manual review, acceptEdits automatically permits in-scope edits and common filesystem commands with documented exceptions, and auto adds background action review. None tells you whether the architecture is a good idea. Our Claude Code Auto Mode guide covers that permission choice in more detail.

The current docs identify auto as the built-in starting mode for interactive terminal and VS Code sessions from v2.1.283, subject to configuration, organization and availability rules. An explicit Plan Mode startup setting still matters. Current starting-mode rules.

Older instructions can miss meaningful changes. Anthropic’s changelog records the /plan description argument in v2.1.72, the clear-context option becoming hidden by default in v2.1.81, and classifier handling of uncertain-read-only Bash commands during planning with auto in v2.1.218. Official changelog.

Worked Example: Share Pricing Logic Without Changing Charges

Consider a concrete refactor: an application calculates checkout prices in its API and renewal prices in a background worker. You want shared pricing rules, while preserving each caller’s existing rounding and discount behavior. This is an illustrative plan, not a report of a tested repository or guaranteed Claude output.

Enter Plan Mode and give it the actual constraint:

Suppose the relevant project files look like this:

A plausible first draft might propose extracting a common calculator, switching both callers, deleting the old helpers and updating the tests. That sounds tidy. It is also incomplete: what happens if checkout rounds at a different point from renewal?

Edit the plan before accepting it. Press Ctrl+G at review and replace the early deletion step with this amendment:

Save the plan and return. If the proposal still needs work, choose the keep-planning option and ask Claude to reconcile the whole plan with that amendment. The point is to remove the contradictory deletion step, not append a warning beneath it. Direct editing and continued planning are documented parts of the workflow. Anthropic’s explore, plan and code guidance.

The revised plan should now read like an implementable sequence:

1. Capture existing behavior. Add cases for current checkout and renewal amounts, including rounding boundaries, discounts and invalid inputs. Resolve any unknown expected result before proceeding.
2. Introduce the shared policy behind adapters. Preserve each existing function’s inputs, outputs and error behavior. Express caller differences explicitly.
3. Move callers in separate steps. Update checkout, verify it, then update renewal. Keep unrelated cleanup out of these changes.
4. Verify the result. Run the project’s actual pricing, API and worker checks, followed by its normal type and integration checks. Review the diff for altered public responses or charge semantics.
5. Retain a rollback path. Keep the compatibility boundary until verification succeeds. Remove obsolete code as a separate, reviewable step.

Then approve with manual edit review for this example. After implementation, check the actual changes and test results against the plan. A plan that mentions tests is still only a proposal until those checks have run.

The economic gain here is specific: catching a behavior change before both callers and their tests are rewritten. There is no need to attach a speculative token-saving percentage to it.

Where Planning First Pays Most

Prioritize work where an early design mistake spreads. In order of likely value, these are the situations I would put through planning first:

These are proposed workflows, not measured results. They follow Anthropic’s recommendation to plan when the approach is uncertain, the change spans files or the code is unfamiliar. For a typo, a known log statement or a clearly scoped rename, ask for the change directly. When Anthropic recommends planning.

For budgeting, compare the workflow before and after. Direct execution spends implementation and review time before you discover a wrong approach. Planning adds investigation and plan-review time upfront, with the possibility of avoiding that rework.

Planning pays when its labor cost plus added model usage costs less than the expected rework it prevents. That is a decision rule, not an Anthropic savings benchmark. Use your own engineering costs and actual usage. If the plan would simply repeat a change you can already specify precisely, skip it.

What Is Worth Building Around This?

The strongest opportunity is a refactor review pack for teams: turn a proposed change into a reviewer-ready file map, preserved contracts, acceptance checks and rollback notes. An engineering lead could pay for consistency across developers, especially around shared business logic.

DataForSEO’s US keyword estimates retrieved on October 12, 2026 put “code refactoring tools” at 170 searches per month. That is a modest signal of interest in the job, not evidence that those searchers will buy a plan-review product. The smallest useful product could accept an exported plan and a repository file map, check for missing callers or unsupported assumptions, and produce a pull-request brief. The catch: generic plan generation is already part of Claude Code. The product needs team-specific checks and a useful review artifact to earn its place.

A narrower opportunity is a migration readiness pack for agencies: produce an affected-component inventory, staged rollout checklist and unresolved-decision list before quoting an upgrade. The same DataForSEO check estimates 20 US monthly searches for “code migration tools.” That small commercial query is a reason to validate with existing clients before building a broad product.

Its smallest version could focus on one migration family and require links to the applicable vendor documentation beside each change. The catch is upkeep: version-specific migration rules age quickly. Plan Mode can support investigation, but it does not supply a verified migration rulebook. These are product hypotheses grounded in query demand, not revenue forecasts.

Ultraplan Is No Longer Available

Anthropic has removed the Ultraplan research preview, including /ultraplan, its keyword trigger and the plan-approval option for refining with Ultraplan on the web. Its page says research previews are experimental and may change or be removed based on feedback. It points readers to local Plan Mode and Claude Code cloud sessions for planning workflows. Anthropic’s current Ultraplan page.

Questions You Might Have Before Your Next Run

On Monday, take the next refactor with shared callers, enter Plan Mode and ask for the preserved behavior, affected files, verification and rollback. Edit the weakest assumption before approving. Pair it with the broader review habits in Claude Code Best Practices.

If your team needs a repeatable planning and review workflow, we can build it into your development process.