Workbranch › Guides

How to use plan mode in Claude Code

Letting Claude Code edit files straight away is fast, until it heads in the wrong direction across ten files. Plan mode makes it research first and show you a plan, and in most setups it can't edit your files until you approve. Here is how to turn it on, review the plan and decide when it's worth it.

Updated 30 October 2026

Keys and option names below were checked against Anthropic's Claude Code documentation as of October 2026. The wording of options can change between versions.

What plan mode does

Plan mode is one of Claude Code's permission modes. In it, Claude can read your files and run shell commands to understand the code, then writes a plan for the change. Edits to your source are blocked until you approve that plan. You review the approach once, up front, instead of judging edit after edit.

Turn plan mode on

There are four ways, depending on how often you want it.

• Mid-session: press Shift+Tab to cycle through the modes until the status bar reads ⏸ plan mode on. Pressing it again leaves plan mode without approving anything.
• Together with a task: start the prompt with /plan, for example /plan add rate limiting to the login endpoint.
• At startup: run claude --permission-mode plan.
• As the project default: in the project's .claude/settings.json, set "defaultMode": "plan" inside "permissions". In the VS Code extension, set claudeCode.initialPermissionMode to plan in your user settings instead, because VS Code doesn't read the project setting for the starting mode.

Review and approve the plan

1. With plan mode on, describe the task and what a good result looks like. Mention files or constraints you already know about.
2. Let Claude explore. It reads code and may run commands; depending on your setup, some commands ask for your approval.
3. Read the plan it presents. Check which files it wants to change, the order of steps, and how it will test the result.
4. To change the plan yourself, press Ctrl+G. The plan opens in your default text editor; save it and Claude works from your version.
5. Choose an option:
   • Yes, and use auto mode (shown as Yes, auto-accept edits when auto mode isn't available): approve and let Claude make the edits without asking each time.
   • Yes, manually approve edits: approve, but review every edit.
   • No, keep planning: stay in plan mode and tell Claude what to change.

Approving leaves plan mode and switches to the mode you picked, and Claude starts working. It also gives the session a generated title if you haven't named it. If the showClearContextOnPlanAccept setting is on, there is an extra first option that approves the plan and clears the planning conversation.

When to use plan mode

• Changes across several files, such as a refactor or a new feature, where a wrong approach is costly to undo.
• Code you don't know yet. Anthropic suggests plan mode for exploring a codebase before changing it.
• Work where you want a say in the approach: adjust the plan with Ctrl+G before any file is touched.
• Usually not needed for small, obvious fixes like a typo, where reviewing a plan takes longer than the edit.

Putting your test commands and conventions in a CLAUDE.md file gives the plan better material to work from.

Good to know

• Claude Code comes with the Pro and Max plans as part of the same subscription as the Claude apps; Team and Enterprise members have a separate help article.
• How shell commands are handled while planning depends on the session: with auto mode available, a classifier reviews them by default; without it, commands outside the built-in read-only set ask first.
• Plan files are saved in ~/.claude/plans/ unless plansDirectory points elsewhere.
• One exception to the edit block: in an interactive terminal session where bypass permissions mode is available, Claude is still told to only plan, but Claude Code doesn't enforce it, so an edit attempted while planning can run without a prompt. In -p runs, the Agent SDK and the VS Code chat panel, the block always applies.

If it doesn't work

• Shift+Tab doesn't reach plan mode. Keep pressing: it cycles through all modes. Look at the status bar for ⏸ plan mode on.
• Claude started editing after the plan. That's expected once you choose a Yes option. Choose No, keep planning if you aren't ready.
• The project default isn't applied in VS Code. Use the claudeCode.initialPermissionMode user setting.
• Ctrl+G opens a program you didn't expect. The plan opens in whatever is set as your default text editor, so change that default if you want a different one.

Keep the plan's open points

A plan often raises decisions and follow-ups that outlive the session. With the Workbranch plugin for Claude Code, run /workbranch:save and Claude files the session's tasks, decisions and open questions into a Workbranch project. Workbranch has a 3-day free trial at app.workbranch.ai.

Sources

• Permission modes (Claude Code Docs, checked 2026-10-30)
• Common workflows (Claude Code Docs, checked 2026-10-30)
• Commands (Claude Code Docs, checked 2026-10-30)
• Use Claude Code with your Pro or Max plan (Claude Help Center, checked 2026-10-30)

Frequently asked questions