Plan Mode

Plan mode is useful when the work has unknowns, broad impact, or a high cost of being wrong. It should end with a concrete implementation contract, not with open-ended brainstorming.

In Claude Code, Plan Mode is also a concrete feature: it is one of the built-in permission modes. When Plan Mode is active, Claude reads files and runs shell commands to explore, then writes a plan, but it does not edit your source until you approve. This chapter covers both the discipline of planning and the mechanics of the feature.

What Plan Mode Does

Plan Mode tells Claude to research and propose changes without making them. Specifically:

• Claude can read files and run shell commands to explore the codebase.
• Claude writes a plan describing the proposed changes.
• Claude does not edit your source while the mode is active.
• Permission prompts still apply the same as default mode (for example, a non-read-only command still prompts before running).

In the permission-mode table, plan is listed as "Reads only" for what runs without asking, and is described as best for "Exploring a codebase before changing it."

Entering and Exiting Plan Mode

There are three ways to enter Plan Mode:

To leave Plan Mode without approving a plan, press Shift+Tab again to continue cycling.

To make Plan Mode the default for a project, set defaultMode in .claude/settings.json:

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

Reviewing and Approving a Plan

When the plan is ready, Claude presents it and asks how to proceed. From that prompt you can:

• Approve and start in auto mode.
• Approve and accept edits (switch to acceptEdits).
• Approve and review each edit manually (switch back to default).
• Keep planning with feedback.
• Refine with Ultraplan for browser-based review.

Approving a plan exits Plan Mode and switches the session to the permission mode that the chosen approve option describes, so Claude starts editing. To plan again afterward, cycle back to Plan Mode with Shift+Tab, or prefix your next prompt with /plan.

When To Plan

Use a planning pass when the task touches:

• Routing, authentication, or permissions.
• Shared data models.
• Multiple packages.
• Public content structure.
• Migrations or destructive operations.
• UI flows that need browser verification.

For small, obvious edits, inspect the local context and implement directly.

A Useful Plan

A plan should name:

• The files or modules likely to change.
• The behavior that must stay unchanged.
• The verification commands.
• The unresolved risks.
• The order of work.

Example:

1. Add `en` to locale config and disable fallback for unsupported books.
2. Add English content only for the selected handbook slugs.
3. Filter home, updates, sitemap, and preview APIs by localized availability.
4. Add E2E coverage for `/en` and unsupported English book routes.

Execution Handoff

When moving from plan to implementation, keep the plan nearby but let the codebase correct it. If a local pattern contradicts the plan, inspect the pattern before forcing the planned abstraction.

Planning in the Cloud With Ultraplan

For a richer review surface than the terminal, Ultraplan hands a planning task from your local CLI to a Claude Code on the web session running in Plan Mode. Claude drafts the plan in the cloud while your terminal stays free, then you open it in your browser to comment on individual sections, ask for revisions, and choose where to execute.

Launch it with /ultraplan <prompt>, by including the word ultraplan in a normal prompt, or by choosing the Ultraplan option from a local plan's approval dialog. When the plan is ready you can either approve it to run on the web (and open a pull request from there) or teleport it back to your terminal to implement locally.

Review Questions

• Did the plan identify the real shared surfaces?
• Did implementation stay within those surfaces?
• Did verification cover the risk that made planning necessary?
• Are unsupported states explicit instead of hidden behind fallback behavior?

References

• Choose a permission mode
• Interactive mode
• Common workflows: Plan before editing
• Plan in the cloud with ultraplan