Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

seo-engine: refresh how-to-use-claude-code-plan-mode

chaitanyagiriacee97834283
diff --git a/blog/src/posts/how-to-use-claude-code-plan-mode.md b/blog/src/posts/how-to-use-claude-code-plan-mode.md
index a37db445..cb67ed5d 100644
--- a/blog/src/posts/how-to-use-claude-code-plan-mode.md
+++ b/blog/src/posts/how-to-use-claude-code-plan-mode.md
@@ -1,76 +1,152 @@
---
-title: "How to Use Claude Code Plan Mode"
-description: "How Claude Code's plan mode works: turning it on, what it blocks, what a real headless plan mode run prints, and how to leave it."
+title: "Claude Code Planning Mode: How to Use Claude Plan Mode"
+description: "Claude Code plan mode, checked 29 Sep 2026: the Shift+Tab shortcut, --permission-mode plan, defaultMode, what it blocks, the approval options and opusplan."
date: 2026-09-11
+updated: 2026-09-29
category: guides
categoryLabel: Guides
type: Technical
-primaryKeyword: "how to use claude code plan mode"
-secondaryKeywords: ["how to use claude code plan mode effectively", "how to enable claude code plan mode", "how to exit claude code plan mode", "claude code plan mode shortcut", "claude code plan mode vs accept edits", "should i use claude code plan mode"]
+primaryKeyword: "claude code planning mode"
+secondaryKeywords: ["claude plan mode", "claude code plan mode shortcut", "how to exit plan mode in claude code", "claude code plan mode vs auto mode", "claude code plan mode vs accept edits", "opusplan"]
tags: ["Guides", "Claude Code", "Getting Started", "Human-in-the-Loop"]
faq:
- q: "What is Claude Code plan mode?"
- a: "It is one of Claude Code's permission modes. Claude reads files and runs shell commands to explore, then writes a plan, but does not edit your source. The official docs put it plainly: plan mode tells Claude to research and propose changes without making them, and edits stay blocked until you approve the plan."
- - q: "How do you enable plan mode in Claude Code?"
- a: "Press Shift+Tab during a session to cycle to it, prefix a single prompt with /plan, or start the session already in it with claude --permission-mode plan. The same flag works with -p for headless runs, so scripts and CI steps can start in plan mode too."
- - q: "How do you exit plan mode?"
- a: "Press Shift+Tab again to leave without approving anything, or approve the plan, which exits plan mode for you. The prompt offers Yes, and use auto mode (Yes, auto-accept edits when auto mode is unavailable), Yes, manually approve edits, or No, keep planning, which keeps you in plan mode so you can redirect Claude."
- - q: "Can plan mode edit files?"
- a: "No. Plan mode blocks edits to your source until you approve the plan, even when you ask for the edit directly, and in our headless run Claude declined exactly that request. It does write the plan itself, by default under ~/.claude/plans/ (the plansDirectory setting can move it). The exception is a session started with bypass permissions available, for example with --dangerously-skip-permissions or --allow-dangerously-skip-permissions: Claude is still told to plan, but an edit it attempts then runs without prompting."
- - q: "What is the difference between plan mode and accept edits mode?"
- a: "Accept edits mode auto-approves file writes and common filesystem commands like mkdir and mv, so you review changes afterward. Plan mode is the phase before that: read and explore only, meant to run first so you can approve or redirect the plan before anything gets written."
- - q: "Should you use plan mode for every task?"
- a: "No. Claude Code's own best practices docs, checked 11 Sep 2026, say planning matters most when you're uncertain about the approach, the change touches multiple files, or you don't know the code well, and that you can skip it when you could describe the diff in one sentence. For a small, obvious fix, just ask Claude to make it directly."
+ a: "It is one of Claude Code's permission modes. Claude reads files and runs shell commands to explore, then writes a plan, but does not edit your source until you approve that plan."
+ - q: "What is the shortcut for plan mode in Claude Code?"
+ a: "Shift+Tab cycles permission modes, and plan mode is three presses away from auto mode, the mode new interactive sessions start in from Claude Code 2.1.283. On Windows terminals where Shift+Tab does not register, Alt+M does the same job. You can also type /plan, or start with claude --permission-mode plan."
+ - q: "How do you exit plan mode in Claude Code?"
+ a: "Approve the plan, or press Shift+Tab to leave without approving anything. The approval prompt offers Yes, and use auto mode, Yes, manually approve edits, and No, keep planning. Approving switches the session to the mode you picked and Claude starts editing."
+ - q: "Can Claude run shell commands in plan mode?"
+ a: "Yes. Plan mode blocks edits to your source, not exploration. Read-only commands run, and other shell commands either go to the auto mode classifier (when auto mode is available and useAutoModeDuringPlan is on, the default) or ask you first."
+ - q: "Which model does Claude Code use in plan mode?"
+ a: "The session's model, unless you pick the opusplan alias, which runs Opus while you plan and Sonnet once you approve. A Haiku session also moves up to Sonnet for planning. The built-in Plan subagent inherits the main conversation's model."
+ - q: "Does plan mode use more tokens?"
+ a: "It adds a research phase before any edit, and the Plan subagent's requests count toward the same usage limits as your main conversation, per the subagents docs checked 29 Sep 2026. For a change you could describe in one sentence, Anthropic's own best practices page says to skip the plan."
---
-<div class="callout tldr"><span class="ic">TL;DR</span><p>Turn on <strong>plan mode</strong> with <code>claude --permission-mode plan</code>, the <code>/plan</code> prefix, or <code>Shift+Tab</code> until the status bar shows plan mode on. Claude reads your codebase and shell output but cannot edit your source, and writes a plan you read before approving it. Approving switches the session to auto mode (accept edits when auto mode is unavailable) or to approving each edit yourself; <code>Shift+Tab</code> again leaves without approving anything. The same flag works with <code>-p</code>, though a headless run has no approval prompt: it just writes the plan and exits.</p></div>
+Claude Code planning mode (plan mode in the docs) is the permission mode where Claude reads your code, runs exploratory commands and writes a plan, but cannot edit your source until you approve it. Enter it with Shift+Tab, the `/plan` prefix, or `claude --permission-mode plan`, and make it the default with `"defaultMode": "plan"`.
-Plan mode is a Claude Code permission mode that makes Claude read your codebase and write a plan before it touches a single file. Turn it on with `claude --permission-mode plan`, the `/plan` prefix, or by pressing Shift+Tab until the status bar shows plan mode on. Nothing gets edited until you approve what it wrote.
+You can do all of this by hand, or use [Munder Difflin](https://harnessmd.com/download), free and open source, to run several Claude Code agents side by side and choose which ones plan first. The last section shows how.
-The rest of this covers how the mode actually behaves, which commands run without asking while it plans, and what a headless run with `--permission-mode plan` really prints, since most writeups describe the behavior without pasting any output. Running several Claude Code sessions at once makes this matter more: a plan per session is one document to read before anything changes, not several diffs to untangle after ([manage multiple Claude Code sessions](/blog/manage-multiple-claude-code-sessions/)).
+Everything below was checked against Claude Code's official docs and changelog on 29 Sep 2026, with Claude Code 2.1.284 installed:
-## How do you turn on plan mode in Claude Code?
+```
+$ claude --version
+2.1.284 (Claude Code)
+
+$ claude --help | grep -A3 -- '--permission-mode <mode>'
+ --permission-mode <mode> Permission mode to use for the session
+ (choices: "acceptEdits", "auto",
+ "bypassPermissions", "manual",
+ "dontAsk", "plan")
+```
+
+## What is the Claude Code plan mode shortcut?
+
+Shift+Tab is the shortcut, and plan mode sits three presses away from where a new session starts. Since 2.1.283 (25 Sep 2026) auto mode is the built-in starting mode for interactive terminal and VS Code sessions on every plan, so the first press goes to Manual, the second to accept edits, the third to plan, and the status bar shows `⏸ plan mode on`. On Windows terminals that don't send Shift+Tab, use Alt+M (interactive mode docs, checked 29 Sep 2026).
+
+| Way in or out (Claude Code 2.1.284, checked 29 Sep 2026) | What it does |
+| :-- | :-- |
+| `Shift+Tab` (Alt+M on some Windows terminals) | Cycles auto → Manual → accept edits → plan, then any optional modes |
+| `/plan` or `/plan fix the auth bug` | Enters plan mode; with a description it starts on that task |
+| `claude --permission-mode plan` | Starts the session in plan mode; works with `-p` too |
+| `"defaultMode": "plan"` under `permissions` in `.claude/settings.json` | Every terminal session in that project starts in plan mode |
+| `claudeCode.initialPermissionMode: "plan"` | Same for the VS Code extension, which ignores project settings here |
+| Approve the plan | Leaves plan mode and switches to the mode you picked |
+| `Shift+Tab` again | Leaves plan mode without approving anything |
+
+The mode Anthropic used to call `default` is now labelled Manual. The rename landed in 2.1.200 on 3 Jul 2026, and `manual` works as an alias wherever you type the value, while hooks and the SDK still see `default` ([Choose a permission mode](https://code.claude.com/docs/en/permission-modes), checked 29 Sep 2026). Guides that say "Normal mode" describe the old label.
+
+## How do you make plan mode the default?
+
+Put it in the project's settings file. Terminal sessions started in that folder then open in plan mode:
+
+```json
+{
+ "permissions": {
+ "defaultMode": "plan"
+ }
+}
+```
+
+Save that as `.claude/settings.json` in the repo. It also works from `~/.claude/settings.json` for every project on the machine.
+
+## What can Claude do in plan mode?
-Three ways, and they all land in the same mode. Press Shift+Tab during a session to cycle to it (the cycle runs `default`, `acceptEdits`, `plan`, then `bypassPermissions` and `auto` if they're available, then back to `default`; Pro, Max and Team sessions start in `auto`, so plan mode is three presses away), prefix a single prompt with `/plan`, or start the session already in it with `claude --permission-mode plan` (checked 11 Sep 2026, [Choose a permission mode](https://code.claude.com/docs/en/permission-modes)). The same flag works with `-p` for non-interactive runs.
+Claude can read, search and run shell commands to explore, but it cannot edit your source. That is where several popular guides go wrong: plan mode does not ban Bash. The official docs say Claude "reads files, runs shell commands to explore, and writes a plan, but does not edit your source". What happens to a given command depends on the session:
-## What does plan mode actually let Claude do?
+* **Auto mode available and `useAutoModeDuringPlan` on** (the default): a classifier reviews each shell command instead of prompting you. Approved ones run, rejected ones are blocked. Since 2.1.218 (22 Jul 2026) this also covers commands the static analyzer cannot prove read-only.
+* **Auto mode unavailable, or that setting off**: anything outside the built-in read-only command set asks you first.
+* **Interactive terminal session with bypass permissions available**: plan mode's blocks are not enforced at all. More on that below.
-Reads, mostly, and not much else. The docs describe it as telling "Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source" (checked 11 Sep 2026, [Choose a permission mode](https://code.claude.com/docs/en/permission-modes)). When auto mode is available and the `useAutoModeDuringPlan` setting is on, which it is by default, a classifier reviews the shell commands Claude wants to run while it plans, instead of prompting you for each one; when auto mode isn't available, anything past the built-in read-only command set still prompts as usual.
+For big codebases Claude hands the reading to the built-in Plan subagent, which has read-only tools (Write and Edit denied) and its own context window. The one file plan mode does write is the plan itself, by default under `~/.claude/plans/`. Set `plansDirectory` to a path inside the project if you want the plan checked in or picked up by a later CI step.
{% img "note-1" %}
## What does a plan mode run actually print?
-We made a two-function `hello.py` in a scratch folder on 11 Sep 2026 and ran Claude Code with `-p --permission-mode plan`, first asking for a suggestion, then asking directly for an edit to see whether plan mode holds:
+It prints a plan and a refusal to edit, even when you ask for the edit outright. On 11 Sep 2026, with Claude Code 2.1.268, we made a two-function `hello.py` in a scratch folder and ran:
```
-$ claude --version
-2.1.268 (Claude Code)
-
$ claude -p --permission-mode plan "Add a multiply function to hello.py right now, actually edit the file."
I haven't edited `hello.py` yet. Plan mode is on, and it blocks every file change except the plan file, even when you ask me to edit right away. I also can't switch plan mode off from here: the tool for that isn't available in this session.
...
The plan is saved at `~/.claude/plans/add-a-multiply-function-buzzing-dolphin.md`. It includes a one-line `python3` check that `multiply(3, 4) == 12`, and that `add` and `subtract` still work.
+```
+
+Told to edit the file, it wrote a memo about editing the file. Fitting, for a paper company's blog. The plan file is still on disk, and on 29 Sep 2026 its first lines read:
-Turn plan mode off (Shift+Tab in the CLI, or restart without plan mode) and tell me to go ahead, and I'll make the edit and run the check.
```
+$ head -4 ~/.claude/plans/add-a-multiply-function-buzzing-dolphin.md
+# Add `multiply` to hello.py
+
+## Context
+The user wants a `multiply` function in `hello.py`, next to the existing `add` and `subtract` functions. Plan mode was on when they asked, so this plan records the change to make once edits are allowed.
+```
+
+A headless run has no approval step. Claude writes the plan, prints a summary and exits. The headless docs add that for `-p` "the built-in starting permission mode is Manual on every plan, so pass the permission mode you want" ([Run Claude Code programmatically](https://code.claude.com/docs/en/headless), checked 29 Sep 2026).
-Told to actually edit the file, it wrote a memo about the edit instead. Fitting, for a paper company's blog.
+## How do you exit plan mode in Claude Code?
-The first prompt, "Read `hello.py` and suggest one small refactor. Do not edit any files.", told Claude not to edit, so it proves less: it printed type-hinted versions of both functions, wrote its plan to `~/.claude/plans/`, and left `hello.py` untouched. The second run above is the real test: asked directly to edit, it still didn't: it read `hello.py`, wrote the plan and never attempted an edit, with no approval prompt to accept.
+Approve the plan, or press Shift+Tab to leave without approving it. When the plan is ready, Claude Code asks how to proceed:
-## How do you get out of plan mode?
+* **Yes, and use auto mode**: approve and continue in auto mode. It reads **Yes, auto-accept edits** when auto mode isn't available, and offers bypass permissions instead if you launched with them.
+* **Yes, manually approve edits**: approve, then review each edit.
+* **No, keep planning**: stay in plan mode and say what to change.
-Two ways: reject everything with another Shift+Tab, or approve the plan, which exits plan mode for you. When the plan is ready, the CLI asks how to proceed: Yes, and use auto mode (it reads Yes, auto-accept edits when auto mode is unavailable), Yes, manually approve edits, or No, keep planning, which keeps you in plan mode so you can redirect Claude (checked 11 Sep 2026, [Choose a permission mode](https://code.claude.com/docs/en/permission-modes)). Press Ctrl+G first if you'd rather open the plan in your own text editor and change it before Claude proceeds.
+Press Ctrl+G at that prompt to open the plan in your own editor and change it before Claude starts. If you want a fresh context for the build, set `showClearContextOnPlanAccept` to `true` and the list gains a first option that approves and clears the planning context. The old **No, refine with Ultraplan on Claude Code on the web** option is gone: Anthropic removed the Ultraplan research preview in 2.1.222 (4 Aug 2026), so any guide that lists four options is out of date.
{% img "note-2" %}
-## Does plan mode work the same in scripts, not just the terminal?
+## Which model does Claude Code use for planning?
+
+Your session's model, unless you choose `opusplan`. That alias runs Opus while you plan and switches to Sonnet once you approve, set with `/model opusplan` or `--model opusplan` ([Model configuration](https://code.claude.com/docs/en/model-config), checked 29 Sep 2026). A Haiku session is upgraded to Sonnet for planning by default. If you're watching a usage limit, the [Max plan tips](/blog/claude-code-max-plan-tips/) cover when Opus planning pays for itself.
+
+## Plan mode vs auto mode vs accept edits: which should you use?
+
+They are phases of one job, not rivals. Plan mode decides what to change, accept edits auto-approves file writes and simple filesystem commands, and auto mode has a classifier review actions instead of you. Anthropic's [best practices page](https://code.claude.com/docs/en/best-practices) says planning helps most "when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified", and to skip it when you could describe the diff in one sentence.
+
+* **Pick plan mode if** the change touches several files, the code is new to you, or you want to redirect Claude before anything is written.
+* **Pick accept edits if** you already know the change and will read `git diff` afterwards.
+* **Pick auto mode if** it's a long task you've already planned and you'd rather not click through prompts.
+
+If one risky command is the real worry, a [PreToolUse hook](/blog/claude-code-hooks-explained/) blocks just that call, and [why Claude Code keeps asking for permission](/blog/why-does-claude-code-keep-asking-for-permission/) explains the prompts you'll see in Manual mode.
+
+## What changed in plan mode in the last six months?
+
+The mechanics held steady; the names and defaults around them moved. From the [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md), with release dates from npm, checked 29 Sep 2026:
-Partly. Plan mode applies in a `-p` run, but there's no approval step: Claude writes the plan, prints its summary, and exits, as the run above shows. Claude Code's own headless docs are direct about the default: "the built-in starting permission mode is Manual on every plan, so pass the permission mode you want" (checked 11 Sep 2026, [Run Claude Code programmatically](https://code.claude.com/docs/en/headless)), unless a project's `permissions.defaultMode` setting already sets `plan`. Passing `--permission-mode plan` in a CI step gets you a proposed change with no edits. Set `plansDirectory` to a path inside the project (the default is `~/.claude/plans`) so a later step can upload the plan for review, the same gate as [approving AI agents without a queue](/blog/human-in-the-loop-approving-ai-agents/).
+| Version | Released | Change |
+| :-- | :-- | :-- |
+| 2.1.200 | 3 Jul 2026 | `default` mode renamed Manual; `manual` accepted as an alias |
+| 2.1.212 | 16 Jul 2026 | Fixed plan mode running `touch`, `rm` and similar without a prompt |
+| 2.1.218 | 22 Jul 2026 | Classifier, not a prompt, judges commands it can't prove read-only |
+| 2.1.222 | 4 Aug 2026 | Ultraplan removed, along with its approval option |
+| 2.1.280 | 22 Sep 2026 | VS Code gains a typed `/plan` |
+| 2.1.283 | 25 Sep 2026 | Auto mode becomes the starting mode on every plan |
-## Plan mode vs accept edits mode: which do you actually want?
+## Does plan mode work with Munder Difflin?
-Different phases of the same job, not competitors. `acceptEdits` mode auto-approves file writes and common filesystem commands like `mkdir` and `mv`, so you review changes afterward in `git diff`; plan mode blocks the edits and hands you a document to read first. Claude Code's best practices page says planning is most useful "when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified" (checked 11 Sep 2026, [Best practices](https://code.claude.com/docs/en/best-practices)). If you only want to gate one risky command rather than a whole session, [Claude Code's hooks](/blog/claude-code-hooks-explained/) can block a single tool call.
+Yes, once you stop Munder Difflin from skipping permissions for that agent. We read this in the source at tag v0.5.3 of the app repo. Auto Mode is on by default (`autoMode: true` in `src/main/config.ts`), and with it on, Claude Code agents launch with `--permission-mode bypassPermissions` (`src/shared/agentProvider.ts`). Each agent is an interactive `claude` in its own terminal, which is exactly the case where Claude Code doesn't enforce plan mode's blocks: Claude is told to plan, but an edit it attempts runs without asking.
-None of this needs Munder Difflin. Each Claude Code agent on the floor is a real `claude` process, but as of Munder Difflin 0.5.2, Auto Mode is on by default and starts it with `--permission-mode bypassPermissions`, and in a session like that Claude Code does not enforce plan mode's blocks (checked 11 Sep 2026, [Choose a permission mode](https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode)). Turn Auto Mode off and restart the agent if you want plan mode to hold for your Claude Code agents. [Download Munder Difflin](https://munderdiffl.in/download) to try it, the classic office is free, and [pricing](https://munderdiffl.in/#pricing) covers the paid plans.
+Two ways around it. In the Add Agent dialog the command field is editable (`src/renderer/src/components/AddAgentModal.tsx`), so replace the prefilled flag with `--permission-mode plan` for the agents you want planning first. Or switch Auto Mode off in Settings, start the agent again, and cycle into plan mode with Shift+Tab in its terminal. Worker requests that already name a `--permission-mode` keep it (`src/main/workerLaunch.ts`). What Munder Difflin doesn't have yet is its own plan review screen: approval happens in Claude Code's prompt, inside the agent's terminal. Running several sessions at once is where a plan per agent pays off, as covered in [managing multiple Claude Code sessions](/blog/manage-multiple-claude-code-sessions/).