Short answer: plan mode is a permission mode in Claude Code where the model explores your codebase and proposes an approach without touching your files. Anthropic’s documentation describes it precisely: in plan mode Claude reads files and runs read-only shell commands to explore but does not edit your source files, and with auto mode available, classifier-approved commands also run. It is labelled Plan in the CLI and the VS Code extension. You reach it by pressing Shift+Tab to cycle permission modes, or by starting a session with claude --permission-mode plan. It costs nothing extra; it is a mode, not a paid feature.
What Is Included
Plan mode sits alongside the other permission modes Claude Code offers, and the differences are worth knowing because they determine how much you have to supervise.
Anthropic documents the modes as follows. default, labelled Manual in the CLI, the VS Code and JetBrains extensions and the desktop app, prompts for permission on first use of each tool. acceptEdits automatically accepts file edits and common filesystem commands such as mkdir, touch, mv and cp for paths in the working directory or additionalDirectories. plan explores without editing. auto auto-approves tool calls with background safety checks that verify actions align with your request. dontAsk auto-denies tools unless pre-approved. bypassPermissions skips permission prompts except for actions no mode auto-approves.
What you get in plan mode specifically is full read access and no write access. Claude can open files, follow imports, run read-only shell commands to understand the project, and build an accurate picture of how something works before proposing a change. What it cannot do is edit your source.
That constraint is the entire value. The most expensive failure in agentic coding is not a wrong answer, it is twenty confident edits in the wrong direction that you then have to unpick.
How to Turn Plan Mode On
Three routes, depending on how you work.
- Cycle with Shift+Tab. Anthropic documents this key as cycling through default, acceptEdits, plan, and when available bypassPermissions and then auto. From auto, the first press switches back to default. On Windows, Alt+M does the same when the Node or Bun runtime does not enable VT input mode.
- Start the session in plan mode. Pass the flag:
claude --permission-mode plan. The CLI reference notes this lets you begin in a different mode like plan and switch to bypassPermissions later. - Set it as a default for dispatched sessions. The same reference documents passing
--permission-modealongside--model,--effortor--agentto set defaults for dispatched sessions, which is useful when you run work in the background.
Check the mode indicator before you start describing a task. The most common mistake with plan mode is assuming you are in it when you are not.
The research, plan, implement pattern
The pattern that gets the most out of this mode has three distinct stages, and the discipline is in keeping them separate.
Research. In plan mode, ask Claude to investigate rather than to fix. “Explain how authentication works in this codebase, including where tokens are refreshed and what happens when refresh fails.” You are buying an accurate mental model, and you can verify it against what you already know, which is your check on whether the rest will be sound.
Plan. Still in plan mode, ask for an approach: which files change, in what order, what the risks are, what should be tested. Ask it to write that plan to a Markdown file so it survives the session and can be reviewed by someone else. A good plan names the files, states the sequence, and is explicit about what it is uncertain about.
Implement. Switch modes and execute against the agreed plan. Because the plan is written down, you can check each step against it rather than reviewing a large diff with no reference point.
The common workflows documentation also covers delegating research to subagents, which pairs naturally with this: exploration is exactly the kind of work worth pushing into a separate context.
What a good plan actually contains
Most disappointing plans are disappointing because the request was underspecified. A plan worth implementing against has five things in it, and asking for them explicitly changes the output considerably.
It names files. “Update the auth middleware” is not a plan; “modify src/auth/middleware.ts and src/auth/refresh.ts, add a test in tests/auth/refresh.test.ts” is.
It states a sequence with a reason. Doing the migration before the code change, or the reverse, is usually a decision with consequences, and a plan that does not explain the ordering has not thought about it.
It identifies what could break. Which callers depend on the current behaviour, what happens to in-flight requests during a deploy, whether the change is backwards compatible.
It says what it is uncertain about. This is the most valuable section and the one you have to ask for. A model that lists three assumptions it could not verify from the code is giving you exactly the list to check yourself.
It defines the check. How you will know the change worked, in terms of a test or an observable behaviour rather than “it should work”.
Ask for those five, and the plan becomes a document you can hand to a colleague rather than a paragraph of intent.
Value and Comparison Notes
| Mode | Writes files | Best for | Main risk |
|---|---|---|---|
| default (Manual) | With a prompt each time | Careful work on unfamiliar code | Prompt fatigue leading to reflex approval |
| plan | No | Understanding, designing, reviewing an approach | Forgetting to switch out of it |
| acceptEdits | Yes, automatically | Well-scoped mechanical changes | Edits you did not review |
| auto | Yes, with safety checks | Trusted repetitive work | Over-trust on consequential changes |
| bypassPermissions | Yes, no prompts | Sandboxes and throwaway environments | Everything |
The comparison that matters most is plan against acceptEdits, because those are the two people actually alternate between. Use plan when you do not yet know what the right change is. Use acceptEdits when you do, and the work is mechanical.
There is a cost argument too. Long agentic sessions consume context, and context is what consumes your usage allowance. A session that edits in the wrong direction for twenty minutes and then reverses costs far more than one that spends five minutes reading and then executes cleanly. Anthropic’s Claude Code cost documentation covers how usage works in the terminal, and the live context indicator is the number to watch.
Plans, Billing, and Limits to Verify
Plan mode itself is not a paid tier, and Claude Code access is tied to your subscription. Anthropic’s support documentation explains that Pro and Max subscribers authenticate Claude Code with the same credentials they use for Claude, so one subscription covers both.
Things worth confirming on the official site before you rely on them:
- Which plans include Claude Code, and at what usage level. The pricing page lists Free, Pro, Max 5x and Max 20x, with Max described as offering 5x or 20x more usage than Pro.
- Your billing cycle and whether monthly or annual applies.
- Whether an
ANTHROPIC_API_KEYenvironment variable is set on your machine. Anthropic notes that if it is, Claude Code uses that key for authentication instead of your subscription, which means you are billed per token rather than drawing on your plan. - Any organisation-level policy settings if you are on a Team or Enterprise plan, since permission modes can be constrained centrally.
Pricing Caveats
Prices, plan names and usage allowances change, and nothing on this page should be treated as a current price quote. Verify current pricing on the official site before committing.
Two further caveats are worth stating plainly. First, availability of individual modes varies: Anthropic’s documentation notes that bypassPermissions and auto appear in the cycle only “when available”, which depends on your version and your organisation’s settings. Second, some labels and aliases are version-dependent, with the Manual label and alias documented as requiring a specific Claude Code version or later. If your indicator does not match what you read here, update before assuming something is broken.
Troubleshooting Plan Mode
- Claude edited files anyway. You were not in plan mode. Check the indicator, and remember that Shift+Tab cycles rather than toggles, so an extra press moves you past it.
- The plan is vague. Vague plans follow vague requests. Ask for named files, an ordered sequence, and an explicit list of what it is unsure about.
- It keeps asking to run commands. Plan mode permits read-only shell commands. A command it considers non-read-only will still prompt, which is the mode working correctly.
- The plan disappeared when the session ended. Ask for it as a Markdown file in the repository. A plan in the scrollback is a plan you will lose.
- Shift+Tab does nothing on Windows. Anthropic documents Alt+M as the alternative when the Node or Bun runtime does not enable VT input mode.
Product, Course, App and Platform Experience
There are three routes to getting good at this, and they suit different people. The product documentation is authoritative and terse, which works well if you already know what you are looking for. Hands-on experimentation in your own repository teaches you your specific failure modes and teaches them slowly. A structured course gives you the sequence and the vocabulary, which is the fastest route for anyone who has not already formed habits.
The teams getting the most from this mode treat the plan as the deliverable of the first session, not as a preamble to the real work. A written plan can be reviewed by a colleague, argued with, and corrected before a single line changes, which is a much cheaper place to catch a bad idea than a pull request.
Doing that well is a skill in directing these tools rather than a feature of them: knowing how much context to supply, how to ask for a plan that is checkable rather than plausible, and where the model’s confidence exceeds its knowledge of your system. Learning it in a structured sequence is faster than working it out session by session, and it transfers to every agentic tool rather than to one product. If you want a structured route in, explore Coursiv AI lessons and check current plan details on the official site.
FAQ
Can Claude modify files in plan mode?
How do I activate plan mode?
claude --permission-mode plan. On Windows, Alt+M cycles modes in runtimes that do not enable VT input mode.Does plan mode cost extra?
Does plan mode save usage?
Your Next Step
On your next non-trivial task, start in plan mode and ask for the approach as a Markdown file before anything is edited. Read it properly, correct the two things it got wrong about your system, and only then switch modes and implement against it. Most people who try this once stop working any other way, because the plan turns a large unreviewable diff into a sequence of steps you already agreed to.