Plan mode in Claude Code, Cursor and Codex
In short: Claude Code, Cursor and Codex each have a built-in Plan mode that
makes the agent research and propose an approach before it starts implementing. Press Shift+Tab
or use /plan, review the plan, then approve it (or click Build in Cursor). That is a session mode,
not the same thing as writing a PLAN.md in the repo — see
the plan-first workflow when you want the plan to survive
a new chat or another tool.
This page is a side-by-side of the built-in mode in each tool, checked against official docs on 2026-11-08. It does not replace the wider permission-mode setup in how to stop asking permission for every command. We parsed the JSON snippets below; we did not run an interactive Plan mode session inside Claude Code, Cursor or Codex.
The same idea, three implementations
| Claude Code | Cursor | Codex | |
|---|---|---|---|
| Enter it | Shift+Tab, prefix a prompt with /plan, or claude --permission-mode plan | Shift+Tab or the Agent mode picker; also suggested for complex-sounding prompts | /plan or Shift+Tab |
| What it does | Research, write a plan, and leave your source alone until you approve | Ask clarifying questions, research the codebase, then open a reviewable plan | Gather context, ask clarifying questions, and build a stronger plan before implementation |
| Edits while planning | Blocked until you approve, except in an interactive terminal session where bypass permissions are available | The docs describe it as planning before Agent writes any code | Official docs describe the workflow, not a filesystem lock |
| Where the plan lives | ~/.claude/plans by default, or plansDirectory | Your home directory by default; click Save to workspace to move it into the project | Not documented as a default file path; optional PLANS.md template for longer work |
| Start every session in it | permissions.defaultMode: "plan" (project files are allowed for this value) | Not documented as a settings default | Not documented as a config default |
Claude Code
Plan mode is one of Claude Code's permission modes. The status bar shows ⏸ plan mode on while it is active.
In the CLI, Shift+Tab cycles modes. From auto, the first press switches to Manual (config value
default), then the cycle runs Manual → acceptEdits → plan. Optional modes such as bypass
permissions slot in after plan, with auto last when it is available.
You can also prefix a single prompt with /plan, or start a session already planning:
claude --permission-mode plan
To make every terminal session in a project start in plan mode, put this in the project's
.claude/settings.json:
{
"permissions": {
"defaultMode": "plan"
}
}
Unlike "auto" and "bypassPermissions", "plan" does take effect from a project
settings file. Sessions the VS Code extension starts are different: they do not read a project's
.claude/settings.json for the starting permission mode. There, set
claudeCode.initialPermissionMode to plan in your VS Code user settings. Picking Plan from
the extension's mode indicator applies to that conversation only (Manual, Edit automatically and Auto can be
remembered). In the desktop app, picking Plan also applies to that session only.
What Claude can do while planning
The docs say Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source. Except in interactive terminal sessions with bypass permissions available, edits stay blocked until you approve the plan.
What happens to a shell command during planning is the first of these cases that matches:
- Interactive terminal sessions with bypass permissions available: neither the classifier nor a prompt applies to
planning commands. Claude is still instructed to plan without editing, but a file edit or shell command it attempts
during planning runs without prompting. Explicit ask rules and recognized critical-path
rm/rmdircommands still prompt. - Auto mode available and the
useAutoModeDuringPlansetting on (the default): the classifier reviews shell commands other than critical-path removals instead of prompting you. Approved commands run, and rejected ones are blocked. - Auto mode not available, or
useAutoModeDuringPlanoff: commands outside the built-in read-only set prompt for approval, including when the sandbox's auto-allow mode is enabled.
Plan mode keeps those edit blocks wherever Claude Code runs without an interactive terminal, including
claude -p, Agent SDK sessions, and the VS Code extension's chat panel.
If you want a prompt for every non-read-only command while planning, turn the setting off. It lives in user, local
or managed settings (or --settings), not in a project's checked-in .claude/settings.json —
a repository cannot turn it off for you. It appears in /config as “Use auto mode during plan”:
{
"useAutoModeDuringPlan": false
}
If auto mode itself is missing or the classifier keeps failing, see Claude Code auto mode unavailable or classifier blocked.
Review and approve a plan
When the plan is ready, Claude presents it and asks how to proceed:
- Yes, and use auto mode — approve and start in auto mode. If auto mode is not available, this option reads Yes, auto-accept edits. If you started the session with bypass permissions enabled, it reads Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session.
- Yes, manually approve edits — approve and review each edit individually.
- No, keep planning — stay in plan mode and tell Claude what to change.
Approving a plan exits plan mode and switches the session to the permission mode that option describes, so Claude
starts editing. Press Shift+Tab again to leave plan mode without approving a plan, or prefix a later
prompt with /plan to plan again.
Press Ctrl+G to open the proposed plan in your default text editor and edit it before Claude proceeds.
When showClearContextOnPlanAccept is enabled (default false, any settings file), the approval
list gains a first option, Yes, clear context and …, that approves the plan, clears the
conversation context, and starts implementing from the plan alone. The rest of the label names the permission mode
the session continues in and how much context the planning used. Accepting a plan also gives the session a generated
title based on the plan, unless you have already named the session.
Where Claude writes plan files
By default Claude Code stores plan files in ~/.claude/plans. Those files (or the directory you set
with plansDirectory) are one of the exceptions to Claude Code's protected-path write rules, so Claude
can update the current session's own plans.
To keep plans inside the project instead, set plansDirectory to a path relative to the project root.
The docs' own example is:
{
"plansDirectory": "./plans"
}
Claude Code falls back to ~/.claude/plans when the path would resolve outside the project root (for
example "../plans") or when the resolved path contains a backslash on macOS, Linux or WSL (write
"docs/plans", which also works on Windows, instead of "docs\plans").
Cursor
Cursor's Plan Mode creates a detailed implementation plan before Agent writes any code. Open the Agent panel
(Cmd+I on macOS, Ctrl+I on Windows and Linux) and press Shift+Tab from the
chat input to rotate to Plan. You can also pick it from the mode picker dropdown. Cursor suggests Plan mode
automatically when you type keywords that indicate a complex task.
The documented loop is:
- Agent asks clarifying questions so it understands the requirements.
- It researches the codebase to gather relevant context.
- It creates an implementation plan.
- You review and edit the plan through chat or markdown files. The help page says the plan opens as a virtual file you can read and edit.
- Click Build when you are ready for Agent to start coding.
Plans are saved by default in your home directory. Click Save to workspace to move a plan into the project for later reference, team sharing and documentation. The official pages do not name a more specific folder than “your home directory” and “your workspace”.
Cursor says Plan mode works best for complex features with more than one valid approach, tasks that touch many files or systems, unclear requirements, and architectural decisions you want to review first. For a quick change or a task you have done many times, jumping straight to Agent mode is fine.
If Agent builds something that does not match what you wanted, go back to the plan instead of trying to patch it with follow-up prompts. Revert the changes, refine the plan so it is more specific, and run it again. The help page points at the Revert button on a previous chat message for rolling files back to that stage. What that does and does not roll back is covered in undo an AI agent's changes.
Codex
Codex's best-practices guide says that for most people, Plan mode is the easiest and most effective way to handle
a task that is complex, ambiguous or hard to describe well. It lets Codex gather context, ask clarifying questions,
and build a stronger plan before implementation. Toggle it with /plan or Shift+Tab.
In the CLI composer:
- Type
/planand press Enter to switch the active chat into plan mode. - Optionally add the request on the same line, for example
/plan Propose a migration plan for this service. - You can paste content or attach images along with that inline prompt.
Codex then enters plan mode and uses the optional text as the first planning request. While Codex is already
working, /plan is temporarily unavailable. In the ChatGPT desktop app and the IDE extension, the same
/plan command is listed as “Toggle plan mode for multi-step planning.”
Official Codex docs describe that workflow; they do not document a filesystem lock equivalent to Claude Code's “edits stay blocked until you approve.” If you need a hard guarantee that nothing in the tree changes while you read the plan, check the session (and your usual approval and sandbox settings) rather than assuming Plan mode itself is a write barrier.
For longer-running or multi-step work, the same best-practices page says you can configure Codex to follow a
PLANS.md or execution-plan template. That is closer to keeping a file in the repo than to the
session toggle, and it pairs naturally with a root PLAN.md (see below).
Plan mode is not a PLAN.md
The built-in mode steers one chat. The plan it produces is easy to lose:
- Claude Code writes plan files under
~/.claude/plansunless you setplansDirectoryto a project-relative path. - Cursor saves plans in your home directory until you click Save to workspace.
- Codex does not document a default plan-file location for the session mode.
None of that is shared automatically with the next tool you open, or with a teammate on another machine. If the
plan should outlive the chat, copy the parts you want to keep into a PLAN.md in the repo and work
through it in small verified steps. That habit is the
plan-first workflow: /plan-feature writes goals,
steps and acceptance checks to the file before any code, then you build one step at a time and review the diff
before you commit.
A useful split:
- Use built-in Plan mode to research the codebase and agree the approach in the current tool.
- Use
PLAN.md(or Codex'sPLANS.mdtemplate) when the work spans sessions, tools or people.
A ten-minute checklist
- Start the task in Plan mode with
Shift+Tabor/plan. In Claude Code, confirm the status bar showsplan mode on. - Answer clarifying questions. If the agent starts editing and you did not approve a plan, stop and check which mode you are actually in (Claude Code: bypass-permissions exception; Codex: the docs do not claim a write lock).
- Edit the plan before implementation:
Ctrl+Gin Claude Code, the virtual file or markdown in Cursor. - Approve it (Claude Code) or click Build (Cursor). Pick auto mode only if you are comfortable with the classifier reviewing the implementation commands.
- If the result does not match the plan, revert and refine the plan rather than stacking fixes in the same chat.
- Copy anything you will need tomorrow into
PLAN.md. In Cursor, click Save to workspace if the plan should live in the repo. In Claude Code, setplansDirectoryto"./plans"if you want the files next to the project. - For a repo where every Claude Code terminal session should start by planning, commit the
defaultMode: "plan"snippet above. Remind VS Code users to setclaudeCode.initialPermissionModethemselves.
FAQ
How do I turn on Plan mode in Claude Code, Cursor or Codex?
In all three, press Shift+Tab from the input to cycle into Plan mode. In Claude Code you can also prefix a single prompt with /plan, or start a session with claude --permission-mode plan. In Codex, type /plan (optionally followed by the planning request); that command is temporarily unavailable while Codex is already working. In Cursor, use Shift+Tab or the mode picker in Agent; Cursor also suggests Plan mode when you type keywords that sound like a complex task.
Can Claude Code edit my source files while plan mode is on?
Usually no. The docs say Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source, and edits stay blocked until you approve the plan. The exception is an interactive terminal session where bypass permissions are available: Claude is still instructed to plan without editing, but a file edit or shell command it attempts during planning runs without prompting. Ask rules and recognized critical-path rm commands still prompt there. Plan mode keeps its blocks in the VS Code chat panel, in claude -p runs, and in the Agent SDK.
Where does Cursor save plans?
Cursor's docs say plans are saved by default in your home directory. Click Save to workspace to move a plan into the project so you can keep it, share it with the team, or treat it as documentation. The official pages do not name a more specific folder than that.
Does Codex Plan mode block file writes the way Claude Code does?
Official Codex docs describe Plan mode as gathering context, asking clarifying questions, and building a stronger plan before implementation. They document how to enter it (/plan or Shift+Tab) but not a filesystem lock like Claude Code's "edits stay blocked until you approve". Treat Codex Plan mode as a planning workflow, and confirm in the session that it has not started editing if that matters to you.
Should I use Plan mode or a PLAN.md file?
Use both when the work is large. Plan mode is a per-session setting in each tool: it steers the current chat to research and propose an approach before implementing. A PLAN.md in the repo survives a new chat, another tool, or a teammate who does not share your home-directory plan files. After you accept a built-in plan you care about, copy the parts you want to keep into PLAN.md.
Sources
- Claude Code docs: Choose a permission mode (plan mode, approval options, defaultMode)
- Claude Code docs: All settings (useAutoModeDuringPlan, plansDirectory, showClearContextOnPlanAccept)
- Cursor docs: Plan Mode
- Cursor help: Plan mode (Build, Save to workspace, revert)
- Codex docs (ChatGPT Learn): Developer commands (/plan)
- Codex docs (ChatGPT Learn): Best practices (Plan mode, Shift+Tab, PLANS.md)