What is Claude Code plan mode?
Plan mode is the permission mode for thinking before changing anything. Anthropic's permission modes docs put it this way: "Plan mode tells 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." Edits stay blocked until you approve the plan.
It is one of several modes, next to Manual (default), acceptEdits, auto, dontAsk and bypassPermissions. The docs list its use as "Exploring a codebase before changing it". In practice that means changes where the approach matters more than the typing: a refactor across many files, a feature in code you don't know well, or anything you want to read before it touches disk.
Three details are worth knowing before you rely on it:
- Shell commands still run. When auto mode is available, a classifier reviews shell commands during planning instead of prompting you, and it is on by default (the
useAutoModeDuringPlansetting). Without auto mode, any command outside Claude Code's built-in read-only set asks for your approval. - Research can go to a subagent. When Claude needs to understand your codebase in plan mode, it can hand the research to the built-in Plan subagent, which has read-only tools (Write and Edit are denied), so the exploration output stays out of your main conversation.
- Bypass permissions removes the blocks. In an interactive terminal session where bypass permissions is available, for example one started with
--dangerously-skip-permissions, Claude Code does not enforce plan mode's blocks. Claude is still told to plan without editing, but an edit it attempts runs without a prompt (explicit ask rules and critical-path removals still prompt). If you want a hard stop, don't start the session that way.
How do you turn on plan mode in Claude Code?
Press Shift+Tab until the status bar shows ⏸ plan mode on, or start your prompt with /plan. These are the ways to switch it on yourself:
| Where | How | Lasts for |
|---|---|---|
| During a session | Shift+Tab cycles Manual, accept edits, then plan (from auto, the first press goes to Manual; bypass permissions and auto slot in after plan when enabled) | Until you press it again or approve a plan |
| One prompt | /plan, or /plan fix the auth bug to start planning that task at once | Until you approve or leave |
| A new session | claude --permission-mode plan | That session |
| Every terminal session in a project | permissions.defaultMode set to "plan" in .claude/settings.json | Every new session in that project |
| VS Code extension | Plan in the mode indicator, or claudeCode.initialPermissionMode set to plan in your VS Code user settings | Picking Plan applies to that conversation only |
To leave plan mode without approving anything, press Shift+Tab again. Claude also has an EnterPlanMode tool of its own, which switches the session to plan mode to design an approach before coding.
How do you approve, edit or reject a plan?
When the plan is ready, Claude shows it and asks how to go on. You can approve it, approve it and review each edit, or keep planning. The options in the current docs are:
- Yes, and use auto mode. Approve and continue in auto mode. If auto mode isn't available to your session, this reads "Yes, auto-accept edits". With bypass permissions enabled, it offers to switch to bypass permissions instead.
- Yes, manually approve edits. Approve, then review each edit as it comes.
- No, keep planning. Stay in plan mode and tell Claude what to change.
Approving exits plan mode, and Claude starts editing. Before you approve, press Ctrl+G to open the plan in your text editor and change it yourself. That is often quicker than describing a fix in chat. Accepting a plan also names the session after the plan, unless you already named it.
Planning can use a lot of context. If you turn on showClearContextOnPlanAccept, the menu gets an extra first option that approves the plan, clears the conversation and starts the work from the plan alone. It is off by default.
Where does Claude Code save the plan?
In a Markdown file under ~/.claude/plans, unless you set plansDirectory. The setting takes a path relative to the project root, such as "./plans". If the path would land outside the project root, or contains a backslash on macOS, Linux or WSL, Claude Code falls back to ~/.claude/plans.
The file is what keeps the plan alive in a long session. Per the context window docs, when a conversation is compacted, "The plan Claude wrote in plan mode" is "Re-injected from disk". Hooks can read it too: the input for the ExitPlanMode tool carries the plan's Markdown and its file path, and after approval a PostToolUse hook gets the approved plan in tool_response.plan.
Which plan mode settings are worth changing?
Most teams only need two: where plans are saved, and whether sessions start in plan mode. Here are the plan-related settings and options in the Claude Code settings reference as of November 2026:
| Setting | What it does | Default |
|---|---|---|
permissions.defaultMode | Starts sessions in a permission mode. "plan" in a project's .claude/settings.json applies to terminal sessions there | Unset. Interactive terminal and VS Code sessions then start in auto mode (Claude Code v2.1.283 or later); claude -p starts in Manual |
plansDirectory | Where plan files go, relative to the project root | ~/.claude/plans |
showClearContextOnPlanAccept | Adds "Yes, clear context and ..." to the approval menu | Off |
useAutoModeDuringPlan | Lets the auto mode classifier review shell commands while planning; false gives you a prompt instead. A false in the project's .claude/settings.json is ignored, so set it in user or local settings | On |
opusplan (a model, set with /model opusplan) | Uses Opus in plan mode, then Sonnet for the work | Not set |
A project file that starts every session in plan mode, keeps plans in the repo and offers the clear-context option looks like this:
{
"permissions": {
"defaultMode": "plan"
},
"plansDirectory": "./plans",
"showClearContextOnPlanAccept": true
}
Keeping plans in ./plans puts them in your repository, so they show up in git status. Decide whether to commit them or add the folder to .gitignore.
Plan mode vs spec-driven development: which do you need?
Plan mode is for one change in one session. A spec is for work that several people or agents build against over days. Spec-driven development tools such as Spec Kit, Kiro and OpenSpec write specs and a task list as files in the repo, and the team reviews them before any code. Plan mode is lighter: one plan, written in your session, approved by you.
Rule of thumb: if the change fits in one pull request and you are the only reviewer, plan mode is enough. If it needs agreement from others, or will be split across several agents, write the spec. Either way, the plan needs a place where everyone else can see it.
How do you share a Claude Code plan with your team?
Turn each step of the approved plan into a card on a shared board. By default the plan sits in your home folder on your machine. Teammates can't see it, other agents can't read it, and nobody can tell which step is done without asking you. A board fixes that: one card per step, in order, with each card's status visible to everyone.
You can do it from inside the plan. Connect Claude Code to the Flux MCP server with a key that has the Write scope, then ask for the plan like this, with the card step written in:
/plan Add CSV export to the Orders page. Write the plan as numbered steps. Make each step small enough to review on its own, and give each one: - the goal, in one sentence; - the files it touches; - a check that proves it works (a test name or a command). Put open questions at the end, not inside the steps. Make step 1 "Create the cards": - Call get_board on Flux board BOARD_ID (the short ID in the board's URL) to get the board UUID and the UUID of the Backlog column (or the first column if there is no Backlog). - For each later step, in order, call create_card in Backlog. Title: "CSV export <step number>: <goal>". Description: the goal, the files, the check, and "Plan: CSV export". - Skip any step whose title is already on the board. - Then stop and list the cards you created. Don't start step 2 until I say so.
Ask for cards small enough to review one at a time. Our post on breaking work down for AI agents covers how small that is. Creating the cards is a write, so it belongs after approval, not during planning. Making it step 1 does that: Claude creates the cards as soon as you approve, then stops. From there you can hand cards to different agents, or let the same session work through them, moving each card to In Progress and then to Needs review, as in our kanban board for AI agents guide.
Why the prompt is written this way, checked against the Flux MCP server code on November 1, 2026:
- UUIDs, not short IDs.
get_boardaccepts the board's short ID or UUID and returns the board's UUID and every column's UUID.create_cardneeds both UUIDs. - The order holds.
create_cardadds each card to the bottom of its column, so creating cards in step order keeps the plan's order. - Only the text fields.
create_cardtakes a title, a description and an optional priority, with no due date, labels or assignees. Put the goal, files and check in the description, which is where an agent reading the card withget_cardwill find them. - No retry protection. Over MCP there is no idempotency key, so a repeated
create_cardcall makes a second card. That is why the prompt checks the board for existing titles first. - Not logged, and no live update. Changes made over MCP are not yet written to the Flux activity log, and
create_carddoesn't send the live update that changes in the app do, so someone with the board open may need to reload to see the new cards. - Whose name is on it. Cards and comments created with an API key show under the name of the person who created the key, so sign agent comments, for example with a "[claude]" prefix.
- Who can do it.
create_cardneeds a Write-scope key, and the key's owner must be at least a member of the board's workspace.
If you use this pattern every time, move the card step out of your prompt and into a skill or your CLAUDE.md, so every plan gets it. Our post on Claude Code skills shows a skill that works a Flux card from Ready to Needs review.