Skip to content

// Engineering - November 1, 2026

Claude Code plan mode: how to use it, and share the plan.

Claude Code plan mode is a permission mode in which Claude reads your code and writes a plan, but does not edit your source until you approve it. Turn it on with Shift+Tab, a /plan prompt or claude --permission-mode plan. Claude saves the plan as a Markdown file, by default in ~/.claude/plans.

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 useAutoModeDuringPlan setting). 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_board accepts the board's short ID or UUID and returns the board's UUID and every column's UUID. create_card needs both UUIDs.
  • The order holds. create_card adds each card to the bottom of its column, so creating cards in step order keeps the plan's order.
  • Only the text fields. create_card takes 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 with get_card will find them.
  • No retry protection. Over MCP there is no idempotency key, so a repeated create_card call 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_card doesn'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_card needs 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.

// FAQ
06 questions
01

What is plan mode in Claude Code?

+

Plan mode is one of Claude Code's permission modes. 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, and approving switches the session to the mode you pick so Claude can start the work.

02

How do I turn plan mode on and off?

+

Press Shift+Tab until the status bar shows plan mode on, type /plan with an optional task description, or start a session with claude --permission-mode plan. Press Shift+Tab again to leave without approving. Approving a plan also leaves plan mode. To start every terminal session in a project in plan mode, set permissions.defaultMode to plan in .claude/settings.json.

03

Can Claude edit files in plan mode?

+

Not until you approve the plan, with one exception. In an interactive terminal session started in a way that puts bypass permissions in the mode cycle, for example 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, apart from explicit ask rules and critical-path removals.

04

Where does Claude Code save plans?

+

In ~/.claude/plans by default. The plansDirectory setting moves them to a folder relative to the project root, such as ./plans. If the path resolves outside the project root, Claude Code falls back to ~/.claude/plans. After the conversation is compacted, Claude Code re-injects the plan from disk.

05

What is opusplan in Claude Code?

+

opusplan is a model setting that uses Opus while the session is in plan mode and switches to Sonnet once you leave plan mode to carry out the plan. Set it with /model opusplan.

06

Does plan mode work in VS Code and with claude -p?

+

Yes. In the VS Code extension, pick Plan from the mode indicator, or set claudeCode.initialPermissionMode to plan in your VS Code user settings; picking Plan applies to that conversation only. With claude -p, plan mode keeps its blocks, but Claude can only present a plan for approval when the run has a permission host to receive it, such as an Agent SDK canUseTool callback.

// Plan once, share it

Put the plan where your team can see it. One card per step.

Connect Claude Code to a Flux board over MCP, turn each approved plan into cards, and review every step in Needs review. Free to start, and agents that connect with an API key never take a seat.