Plan mode in Claude Code: think before it touches a file
How to start plan mode in Claude Code, read and edit the plan, pick the approval option, and when planning first saves you from a big wrong diff.
Plan mode makes Claude Code read your project and propose a plan without changing any source file. Edits stay blocked until you approve. Start it with Shift+Tab until the status bar says ⏸ plan mode on, with claude --permission-mode plan, or by typing /plan before a prompt. It is the cheapest way to catch a wrong approach before it becomes a forty-file diff.
#How do you turn plan mode on?
Three ways, all equivalent:
claude --permission-mode plan
Or, inside a session, press Shift+Tab to cycle through the permission modes. The cycle goes default, acceptEdits, plan, and the status bar shows ⏸ plan mode on when you land on it. Or type the command with a description, which enters plan mode and starts on the task straight away:
/plan fix the auth bug where refresh tokens are never rotated
To make it the standing default, set permissions.defaultMode to plan in a settings file. All the modes are covered in permission modes explained.
#What does Claude do in plan mode?
It reads files, runs shell commands to explore, and writes a plan. It does not edit your source until you approve. So a good plan-mode prompt asks for investigation plus a proposal:
We need rate limiting on the public API. Read how middleware is wired in
src/server/, look at how auth is done, and propose a plan: which files
change, in what order, and how we test it. Ask me anything that is unclear.
Notice what that prompt contains: the goal, where to look, the shape of the answer, and permission to ask questions. Plans get better when Claude can ask, and worse when it has to guess at requirements.
#How do you approve, edit or reject the plan?
When the plan is ready, Claude asks how to proceed. The options you will see:
- Yes, and use auto mode. Approves and starts editing in auto mode. If auto mode is not available to your session, this reads "Yes, auto-accept edits". If you started with bypass permissions enabled, it offers to switch to that instead.
- Yes, manually approve edits. Approves the plan and keeps asking before each edit.
- No, keep planning. Stays in plan mode so you can say what to change.
There is also an optional setting, showClearContextOnPlanAccept, that adds a first option approving the plan and clearing the planning context. That is handy because the exploration that produced the plan often filled the context window with file reads you no longer need.
Two shortcuts worth knowing. Press Ctrl+G to open the proposed plan in your default text editor, change it, and then let Claude continue: editing the plan yourself is faster than arguing about it. And if you want to leave plan mode without approving, press Esc first and then Shift+Tab, because at the approval prompt Shift+Tab approves the plan.
On approval, the session switches to the permission mode of the option you chose and starts editing. Claude Code also gives the session a title based on the plan, unless you have already named it.
#When is plan mode worth it?
Use it when the cost of going the wrong way is high:
- A change that spans several files or layers (a schema change plus the code that reads it).
- Code you do not know yet. The plan is also your tour of how it works.
- A refactor where the order of steps matters.
- A vague request: planning forces the missing questions into the open.
- Anything you will hand to a teammate or review in a pull request; the plan is the description.
Skip it when you can describe the diff in one sentence ("rename getUser to fetchUser everywhere", "fix this typo"). Planning a one-line change is overhead.
#How do you review a plan well?
Read it as you would read a design proposal:
- Is it the right problem? Check the first lines against what you asked.
- Does it touch only what it should? A plan that mentions files you did not expect usually found a dependency, or misread the task.
- Is there a way to verify? A good plan names the tests or commands that prove the change works. If it does not, say so and send it back with "No, keep planning".
- Are the steps ordered so each leaves the project working? Small steps that each pass tests are easier to review and to undo.
- What did it leave out? Ask "what are the risks and what did you decide not to do?"
Then pick the approval option that matches your trust: manual approval for risky changes, auto-accept for contained ones.
#Where does the plan live, and can it run headless?
The plan files of the current session are stored under ~/.claude/plans/, or in the directory set by the plansDirectory setting. Claude Code treats that folder as protected, so you should not need to touch it by hand. Nothing in it replaces committed documentation: if the plan is worth keeping, ask Claude to put the final version in your repository, for instance in docs/.
The same flag works with claude -p for non-interactive use, which is useful for generating a plan in a script or a CI job and reading it before anything runs for real:
claude -p --permission-mode plan "plan the migration to the new payments client"
#A habit that pays off
Combine the two ends of the workflow: plan first, approve into a permissive mode, then review the diff, which is much smaller than it would have been without a plan. If you are still getting started, the beginner's guide puts this in order, and how to prompt Claude Code covers how to phrase the request.
#In Relais
Relais shows Claude Code's plans as their own card in the conversation, next to the inline approval cards for edits, so you read and answer the plan in the chat. Plan is one of the four permission modes in the composer's picker, and a session template or a workflow step can start in plan mode. See features.