Home › Articles

Plan mode in Claude Code, Cursor and Codex

Updated 2026-11-08

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 CodeCursorCodex
Enter itShift+Tab, prefix a prompt with /plan, or claude --permission-mode planShift+Tab or the Agent mode picker; also suggested for complex-sounding prompts/plan or Shift+Tab
What it doesResearch, write a plan, and leave your source alone until you approveAsk clarifying questions, research the codebase, then open a reviewable planGather context, ask clarifying questions, and build a stronger plan before implementation
Edits while planningBlocked until you approve, except in an interactive terminal session where bypass permissions are availableThe docs describe it as planning before Agent writes any codeOfficial docs describe the workflow, not a filesystem lock
Where the plan lives~/.claude/plans by default, or plansDirectoryYour home directory by default; click Save to workspace to move it into the projectNot documented as a default file path; optional PLANS.md template for longer work
Start every session in itpermissions.defaultMode: "plan" (project files are allowed for this value)Not documented as a settings defaultNot 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:

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:

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:

  1. Agent asks clarifying questions so it understands the requirements.
  2. It researches the codebase to gather relevant context.
  3. It creates an implementation plan.
  4. 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.
  5. 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:

  1. Type /plan and press Enter to switch the active chat into plan mode.
  2. Optionally add the request on the same line, for example /plan Propose a migration plan for this service.
  3. 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:

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:

A ten-minute checklist

  1. Start the task in Plan mode with Shift+Tab or /plan. In Claude Code, confirm the status bar shows plan mode on.
  2. 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).
  3. Edit the plan before implementation: Ctrl+G in Claude Code, the virtual file or markdown in Cursor.
  4. Approve it (Claude Code) or click Build (Cursor). Pick auto mode only if you are comfortable with the classifier reviewing the implementation commands.
  5. If the result does not match the plan, revert and refine the plan rather than stacking fixes in the same chat.
  6. 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, set plansDirectory to "./plans" if you want the files next to the project.
  7. For a repo where every Claude Code terminal session should start by planning, commit the defaultMode: "plan" snippet above. Remind VS Code users to set claudeCode.initialPermissionMode themselves.

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

Official docs, checked 2026-11-08.

Get the free rules sampler + new tips by email

Confirm your email and we'll send you straight to the sampler download. Then one short email every two weeks covering tool format changes (Cursor, Claude Code, Codex, Windsurf, Copilot), new rules and kit updates. No spam.

We store only your email, with our email provider Resend. See the privacy policy.

Unsubscribe anytime from any email. Rather skip email? Get the sampler on GitHub or download the zip directly.