What is Claude Code plan mode?
Claude Code plan mode is a permission mode in which Claude reads files, runs commands to explore, and writes a plan, but does not edit your source. Edits stay blocked until you approve the plan. Turn it on with Shift+Tab, the /plan command or claude --permission-mode plan; approving the plan switches the session to a mode that can edit.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Enter plan mode: press Shift+Tab until the status bar says plan mode on, prefix one prompt with /plan, or start the session with claude --permission-mode plan.
claude --permission-mode planClaude reads files and runs commands to explore. Commands outside the built-in read-only set prompt you, or go to the classifier when auto mode is available.
Edits to your source are blocked. Claude writes a plan instead and presents it when it is ready. Ctrl+G opens the plan in your text editor to change it.
You choose: approve and switch to auto mode (or auto-accept edits), approve but review each edit by hand, or keep planning and say what to change.
Approving leaves plan mode and Claude starts editing in the mode you picked. Shift+Tab leaves plan mode without approving anything.
Plan mode versus the other permission modes
Claude Code has six permission modes, and plan mode is the only one defined by what Claude may not do. Manual mode (default) runs reads without asking and prompts for everything else. acceptEdits also lets file edits and common filesystem commands through. auto lets a classifier model review actions in the background. dontAsk denies anything that would have prompted, for locked-down scripts. bypassPermissions skips every check and is meant for throwaway containers.
Plan mode sits beside these rather than above them. Claude can read, search, and run commands to understand the code, but a source edit is held back until a plan exists and you have said yes. The point is not safety alone; it is sequencing. You get to see the whole approach before the first line changes, which is cheaper than reviewing a diff that already went the wrong way.
One nuance catches people: in an interactive terminal where bypass permissions are available, planning does not enforce the blocks. The docs say an edit or command Claude attempts during planning runs without prompting there. Everywhere without a terminal, such as -p runs, the Agent SDK and the VS Code chat panel, the blocks hold.
Example: a refactor across many files
Say you want to move authentication from middleware into a service layer. In plan mode you describe that, and Claude reads the middleware, finds every caller, runs the test suite to see what passes today, and writes a plan: which files move, in what order, which tests need updating, what it is unsure about. You open the plan with Ctrl+G, cross out the step that touches the billing module, and approve with "manually approve edits". Claude now edits, and you see each change as it comes. Had you started in acceptEdits, the billing change would already be on disk.
If an agent is editing a shared Intraface board for a team, the same habit means the version your teammates see is one deliberate publish rather than a trail of experiments.
When to use it
Use plan mode when you are new to a codebase, when the change crosses more files than you can hold in your head, or when the cost of a wrong edit is high: migrations, auth, anything with a deploy attached. It is the mode for understanding code before changing any of it. Skip it for a one-line fix you could type yourself; the plan would be longer than the change.
The /plan command is the lightweight version. /plan fix the auth bug enters plan mode and starts on that task in one step, so you do not need to cycle modes for a single prompt.
Common mistakes
- Approving without reading. The approval prompt is the whole value. If you always pick the first option, start in
acceptEditsand save the round trip. - Assuming reads are all that runs. Exploration commands do run, and in auto mode a classifier, not you, decides on many of them. Deny rules are the reliable fence.
- Expecting project settings to apply in VS Code. The starting mode there comes from
claudeCode.initialPermissionMode, not from.claude/settings.json. - Treating the plan as the spec. It is Claude's proposal for this session. If the plan matters beyond today, write it into a file the next session can read.
FAQ
- Does Claude Code plan mode block every command?
- No. Reads always run. Shell commands outside the built-in read-only set either prompt you or, when auto mode is available, go through a classifier that approves or blocks each one. Deny rules in your settings still apply, and no allow rule approves an rm of a path Claude Code recognises as critical.
- Can I make Claude Code start in plan mode every time?
- Yes. Set permissions.defaultMode to plan in the project's .claude/settings.json. In VS Code the project setting is not read for the starting mode; set claudeCode.initialPermissionMode to plan in user settings instead.
- Is Claude Code plan mode available in the Agent SDK?
- Yes. Pass permissionMode: "plan" in the options. Edits are never auto-approved there; they go to your canUseTool handler. Plan mode keeps its blocks wherever there is no interactive terminal, including -p runs and SDK sessions.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.