Cursor Plan Mode is a workflow, not a permission mode

You opened Plan Mode in Cursor and assumed it worked the way Claude Code's does. It shares the name, the Shift+Tab shortcut, and the idea of a plan you review before code runs. Beyond that the semantics diverge, and every review post I have read glosses the divergence. If you are treating Cursor Plan Mode as a write-block, you are relying on something Cursor has never put in writing.

I went through Cursor's docs, changelog, pricing, forum threads, and Claude Code's official pages, and this is what actually holds up. Verified on 19 August 2026. Where a claim cannot be traced to a source, I say so rather than repeating it.

TL;DR

Plan Mode is a workflow phase, not a permission mode. Cursor's current docs say Plan Mode "creates detailed implementation plans before writing any code" and stop there. No editor line says file edits are blocked, shell commands are blocked, or write permissions are denied. Cursor 2.4, released 22 January 2026, explicitly fixed "an issue allowing edit tool usage during plan mode execution in CLI," which tells you that the CLI path was writable and needed patching. A forum user on Cursor 2.2.43 reported file edits and Git commits inside Plan Mode.

Claude Code Plan Mode uses a permission contract. The official page says: "Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source." Except in bypass-permission sessions, edits stay blocked until you approve the plan. Approval is an explicit choice with Yes, manual-approval, and keep-planning options.

The plan is a Markdown file. Cursor 2.2, released 10 December 2025, made plan files persistent on disk by default and editable with normal tools. The current docs say plans save to the home directory by default and can be moved to the workspace. The exact default path is not published.

One model can plan, another can build. Cursor 2.0 introduced planning with one model and building with another, plus foreground, background, and parallel-agent options. The default planner model and any Plan-specific setting are not documented.

The handoff is a Build button. Review the plan, then Build, or from Cursor 2.5 (17 February 2026) Build in Cloud. Cursor does not document whether the executor rereads the plan file from disk, uses it as chat context, or both.

Editor shortcut is Shift+Tab on all platforms. The CLI adds /plan and --mode=plan. The keyboard-shortcut page says Shift+Tab rotates between Agent modes and never publishes the full cycle order. The 16 January 2026 CLI changelog documents the slash command and flag for Cursor CLI, not the editor.

Plan Mode availability by tier is not published. The pricing page lists Hobby Free, Pro-family, Teams, and Enterprise. There is no Plan Mode row, no Plan Mode surcharge, and no confirmation that Free includes it. Cloud Agents require a paid plan and on-demand usage.

There is no independent A/B result. Cursor's blog says planning "significantly improve[s] the code generated" without a sample size, baseline, or metric. Independent research is mixed: one end-to-end benchmark found a Design Agent's planning blueprint negatively affected downstream development in one architecture.

Cursor Plan Mode versus Claude Code Plan Mode

Both products use the words Plan Mode, both use Shift+Tab, and both produce a plan you can approve. Beyond that the two rows worth reading in the table below are enforcement and transition.

The line doing the load-bearing work in Claude Code's docs is the one saying edits stay blocked until you approve. Cursor's editor docs have no equivalent line, which is why importing your Claude Code habits into Cursor without checking gets you into trouble.

Claude carries one carve-out worth naming. Its own docs say: "In sessions with bypass permissions available, Claude Code also doesn't enforce plan mode's blocks." Outside those sessions the default posture is a write-block, and that default posture is the one Cursor has never put in writing.

What Plan Mode actually does

Cursor describes the workflow in three moves: the agent asks clarifying questions, researches the codebase, and writes a Markdown implementation plan you can review or edit. The October 7, 2025 announcement is more specific: after planning, "it creates a Markdown file with file paths and code references," and you can add or remove to-dos.

The plan is a real file. Cursor 2.2, released 10 December 2025, says "Plans now saved as files on disk by default" and "Agent plans are now files that can be edited with normal tools." Before 2.2, the plan view could look editable but was internal. A forum thread from 17 November 2025 catches this transition: a user on Cursor 2.0.77 reported the plan Markdown was not editable, and a responder using the handle deanrie said the default plan was internal or virtual and had to be saved to workspace. The responder's staff status was not established in the thread, so treat that clarification as anecdotal rather than official.

Where does the file live? The current docs say: "Plans are saved by default in your home directory." The exact path under the home directory is not stated. If you want the plan in your Git history, or shared with a teammate, or reviewed in a PR, use Save to Workspace and let Git track it like any other file. Cursor does not commit it for you and does not create a Plan branch.

Is Plan Mode read-only?

Plainly: the editor docs never say so. The current page says "Plan Mode creates detailed implementation plans before writing any code," which describes what the workflow is for and stops before saying anything about what the underlying tools can or cannot do.

Three pieces of evidence sit alongside that gap. First, Cursor 2.4 fixed "an issue allowing edit tool usage during plan mode execution in CLI." If Plan Mode had ever been an enforced permission boundary in the CLI, this fix would not have been necessary. Second, the same 2.4 release note describes the interactive Q&A tool used in Plan and Debug mode as one that can leave the agent "reading files, making edits, or running commands while it waits for a response." Third, a forum user on Cursor 2.2.43 alleged the agent "violated Plan Mode by making file edits and git commits." The forum report is anecdotal, and the calendar year on the retrieved excerpt is not exposed, so I cannot pin it to a date.

The honest reading is that Plan Mode in the editor is a planning convention with a review checkpoint, and the sources leave the technical prevention layer around it unspecified. The safety property people carry across from Claude Code, that Plan Mode cannot touch your tree, is one Cursor has left off the page.

So if you need a real write-block, use a clean worktree, a separate branch, a sandboxed VM, or a PreToolUse-style enforcement layer. That advice comes from the gap in the docs plus the CLI patch, and I am flagging it as my judgement rather than a Cursor statement.

Models, handoff, and Build

Cursor 2.0, released 29 October 2025, added Plan Mode in Background and introduced a workflow where "you create your plan with one model and build the plan with another." Foreground, background, and parallel plans are all options. So a distinct planner model is available as a choice, and whether every Plan Mode run uses one is a separate question the docs do not answer.

The Agent overview describes the model as one component of an Agent and calls it "the agent model you pick for the task." No default planner model is published. No plan.model settings key or Plan-specific config field turned up in the docs. So the accurate summary is: planner and executor can be the same or different depending on how you set it up, and if you care which they are, record it yourself.

Flagged as first-hand judgement rather than recommendation: I have never used the split. I leave one model on default for everything, and Plan Mode runs on whatever that model happens to be. The docs make a case for mixing; my own habit is to not bother.

The transition from plan to code is Build. The current page describes a Build action, the October 2025 announcement says "Review or edit the detailed plan, then build directly from your plan when ready," and Cursor 2.5 added Build in Cloud so plan execution hands off to a Cloud Agent while you keep working locally.

Cursor 3.0, released 2 April 2026, mentions plans being included in shared chats alongside the transcript. That is a persistence signal, not a handoff spec. The docs do not say whether Build rereads the saved plan from disk, uses the conversation copy, or reads both. So if you edited the plan file after Build was queued, the safe assumption is that you cannot predict what the executor will see. Save the final plan, verify the executor's first action, and read the diff.

Invocation, shortcuts, and version history

The editor Plan Mode page says: "Press Shift+Tab from the chat input to rotate to Plan Mode." The keyboard-shortcut page lists Shift Tab as "Rotate between Agent modes" and lists Cmd . on macOS and Ctrl . on Windows/Linux as the Mode Menu. The exact editor shortcut is Shift+Tab on every platform. No official source publishes the full current cycle order, so claims like Agent -> Ask -> Plan -> Debug are build-dependent until you verify them in the mode menu.

The 16 January 2026 CLI changelog documents /plan and --mode=plan for Cursor CLI, alongside /ask and --mode=ask for Ask mode. Both belong to the CLI surface, and the editor chat has no equivalent slash command in the docs I checked. If a post tells you /plan is universal, it is fusing two surfaces the docs keep separate.

For the editor, there is no Plan-specific settings.json key, .cursor config key, or documented editor slash command in the pages I checked. The current Rules page lists .cursor/rules, User Rules, Team Rules, and AGENTS.md. It does not list .cursorrules as one of the current four rule types.

Nine releases, incremental fixes, no rename. If you see the phrase "Planning Mode" in the wild, it is a user shorthand rather than an official product name.

Plan Mode versus Agent Mode inside Cursor

The practical difference is workflow and checkpoint, not a fully documented capability firewall. Agent Mode is explicitly described as able to edit and run commands. Plan Mode is described as producing a plan before code. The sources do not establish that Plan Mode's underlying tools are incapable of editing or executing.

Plan Mode carries capabilities Agent Mode does not require: a reviewable plan file, Plan-specific clarifying questions, plan editing with normal tools, selected-to-do delegation to new agents, and a documented Build in Cloud handoff. If your job is scoping a change before touching files, that is where Plan Mode earns its use.

Tiers and pricing

The pricing page lists Hobby Free with limited Agent requests, Pro, Pro Plus, and Ultra for individuals, Teams, and Enterprise. There is no Plan Mode row, no Plan Mode surcharge, and no confirmation that Free tier includes it.

The models-and-pricing page says individual plans have Auto plus Composer and API usage pools, that selecting a specific model draws from the API pool at that model's rate, and that model selection affects how quickly included usage is consumed. No Plan Mode token multiplier, planning fee, or separate Plan Mode request charge is published.

Cloud Agents require a paid plan, use API pricing for the selected model, and require on-demand usage. That requirement covers Cloud Agents alone, and says nothing about whether local Plan Mode requires a paid plan.

So the accurate answer on tiering is: not publicly specified. If you need to write copy for your team about who has access to Plan Mode on which plan, ask Cursor Support and get it in writing, because the pricing page does not say.

Interaction with subagents, Skills, rules, and Cloud

Every one of these is documented independently of Plan Mode. The Plan Mode page does not say that every applicable rule is read during planning, that Skills are auto-loaded, that a saved plan survives compaction, or that Plan Mode resumes automatically in a new session. Cursor 3.0's line about plans being included in shared chats is the closest published persistence signal, and it is not a compaction guarantee.

The subagents doc adds a detail worth carrying: a subagent starts with a clean context and the parent must include the relevant information, because the subagent does not have the prior conversation history. So if selected to-dos go to a new agent, whatever that agent needs has to be in the to-do itself. Do not assume the plan came with it.

Auto-review is a separate run-mode feature. Its 29 May 2026 changelog says it applies to Shell, MCP, and Fetch calls, and gives the settings path Settings > Cursor Settings > Agents > Approvals & Execution. It does not connect those approval rules to Plan Mode's write semantics, so do not assume Auto-review is what makes Plan Mode safe.

Known failure modes worth naming

The most cited recent incident is Build stalling in Cursor 3.0.4. A user with the handle Jev reported that after clicking Build the agent entered an infinite "planning next move" loop and never executed, and that pasting the plan back into the original chat caused execution to resume. A responder using the handle mohitjain said this was "a known issue we're actively tracking," called the copy-back workaround the best available for now, and said the team was working on it. The retrieved forum excerpt shows the staff post as 2d rather than an exact calendar date, so I cannot give a more precise date without inventing one.

The 2.2.43 report of edits and Git commits inside Plan Mode is anecdotal, the calendar year is not exposed in the retrieved excerpt, and it is not evidence of a currently reproducible general behaviour. It is evidence that the mode does not carry a hard guarantee, which is the point the CLI patch also makes.

Historical fixes worth knowing about, since they map the surface area: Cursor 2.3 fixed Plan Mode focus theft, a worktree model mismatch, and unread sidebar states for Plan Mode Q&A. Cursor 2.4 patched the CLI edit-tool issue and improved Q&A behaviour when the agent is left reading files while waiting for a response. None of these are current unresolved bugs.

Some numbers the docs do not publish, worth listing so you stop looking for them: no Plan-specific token budget, no planning-to-execution ratio, no plan-length cap, no measured drift rate. The general Agent docs do say there is no limit on tool calls during a task, and that statement covers Agent Mode rather than Plan Mode.

What the internet gets wrong

These are the claims not to repeat as established facts. For several, no traceable primary source turned up at all.

The Claude analogy is where readers slip up. Claude's docs use permission-mode language and an explicit approval prompt. Cursor's use planning language and a Build button. Carry Claude's mental model across without checking, and you get a false safety assumption in return.

What the evidence actually says about planning helping

Cursor's blog post from 7 October 2025 says: "We've seen this significantly improve the code generated," with no sample size, no baseline, no task set, and no metric attached. That is vendor observation dressed as a result.

Independent research is mixed and none of it tests Cursor specifically.

The most useful counterexample is E2EDevBench (arXiv 2511.04064v1, 6 November 2025). It compares representative end-to-end software-development agent workflows, and reports that a Design Agent's planning blueprint negatively affected subsequent development in one architecture, while a system without a predefined plan interpreted the original requirements directly. It runs on a different tool, different models, and one architecture out of several, and the finding to carry across is that a plan-first workflow can hurt as well as help.

The Agent Planning Benchmark (arXiv 2606.04874, submitted 3 June 2026) is a diagnostic benchmark for planning quality. It reports that APB-guided refinement improves plan correctness on 4,209 multimodal cases across 22 domains. That is about plan quality, not about downstream code quality after Build.

Agentless reports 96 of 300 (32%) on SWE-bench Lite with a three-phase workflow at an average cost of $0.70. It shows a staged workflow can be competitive on that benchmark, and says nothing about Cursor's Plan Mode specifically.

No independent controlled evaluation of Cursor Plan Mode against direct Cursor Agent execution exists, and Cursor has published no numerical A/B result of its own. Treat planning as a useful workflow hypothesis, and read anyone quoting a specific success-rate lift for Plan Mode with the same scepticism.

When Plan Mode earns the friction

Flagged as first-hand judgement rather than measured evidence.

I have used Plan Mode across enough sessions to say two things the docs and forum threads leave out.

In my sessions it has not edited files. It behaves the way the announcement describes: reads through the code, comes back with a breakdown of what it plans to do. The CLI patch and the 2.2.43 report above still stand as reasons to keep the write-block off my assumption list, because a run of clean sessions is a run of clean sessions rather than proof.

The trigger I actually use is smaller than a size threshold. Size and complexity feed in, but the deciding question is whether I can already picture the implementation and its order. If the picture is there, Plan Mode is friction I skip. If it is not, Plan Mode earns the extra step because the plan makes the ordering explicit before I commit to it.

That rule has changed how I use the feature over time. Early on I liked Plan Mode as a general-purpose warm-up. These days I treat it as scope mode, the point where I decide what a ticket is before writing anything. For bigger tickets I sometimes reach for a personal kickoff mode instead, which is my own version of the same idea. More often I split the ticket into smaller ones and skip both.

The question every review of Plan Mode dodges

Most reviews tell you Plan Mode helps with complex changes. Almost none say what it costs, or where the contract runs out.

Cursor's Plan Mode is a review checkpoint over a Markdown file, and the docs stay silent on whether the underlying agent can edit or execute while planning. The CLI patch and the 2.2.43 user report between them are evidence that a writable path has existed on at least two builds. The current editor page addresses none of that. So if you have been treating Plan Mode as a safety layer, the question worth asking is:

What are you actually relying on when you enter Plan Mode?

If the answer is "a plan I will read before Build runs," Plan Mode delivers that. If the answer is "a boundary that stops the agent from touching my tree," you want a branch, a worktree, a sandbox, or an enforcement layer sitting under the agent, because that is what the sources actually support.

What I built for this

anvil is a set of Claude Code skills that treat context as a budget rather than a scratchpad. It is a Claude Code project, but the discipline carries over: every line in a context file is paid every session forever, so the default answer to "should this go in context?" is no.

The rule that applies to Plan Mode, whichever tool you are using: a plan you cannot enforce is a plan you have to read, so enforcement belongs in hooks and settings while the Markdown plan carries the reasoning.

docs/FILE_CONTRACT.md is the written version of the budget discipline. §1 is the load-bearing part.

Start by doing this

2 mins: Open Cursor's Plan Mode page and read the exact sentence about what happens before writing any code. Then open Claude Code's permission-modes page and read the sentence about Claude not editing your source. Notice which one is a description and which one is a contract.

5 mins: In a scratch repo, start Plan Mode in Cursor, ask for a change that touches an obvious file, and watch what the agent does before you click Build. If you see reads only, you have your answer for this session. If you see anything else, you have your answer for this session too.

10 mins: Move whatever plan you generated into your workspace with Save to Workspace, commit it, and treat it like a design doc. That gets you the reviewable artifact Plan Mode is genuinely good at, without depending on any enforcement property that has not been published. And if you are also comparing Cursor and Claude Code head to head, that is a different question with a different answer.