Plan mode / read-only agent
You say “refactor the payments module to use the new transaction API.” The agent starts editing. Before you’ve finished forming a mental model of what it’s doing, it’s three files deep, two abstractions in, and confidently moving toward a design you can already tell you wouldn’t have chosen. Now you’re either reading every diff to catch the wrong turn, or rolling back and starting over with a longer prompt.
The problem isn’t that the agent is wrong. It’s that you handed it a direction and it interpreted that as a go. You wanted to align on approach first. The agent doesn’t pause to align unless you explicitly tell it to.
Plan mode puts the alignment step back where it belongs. In Plan mode the agent can’t edit - or, in some tools, can’t edit without asking you first - so it has to put the plan in front of you instead. You read it, push back, adjust, and only then drop out to execute. The same conversation, with the agreement before the writes rather than after.
The posture is simple: the agent can read, search, grep, and reason - but cannot write, edit, or run mutating commands. You drop into it when you want a plan, a code review, a “tell me what you’d change before you change anything,” or a safe exploration of an unfamiliar codebase.
It’s the same idea everywhere - think first, act later. What the word “mode” hides is how hard the block actually is, and what happens to the plan once you leave.
Real-world examples of when you’d switch into Plan mode:
- Non-trivial refactors - anything touching more than two files. Have the agent map the change set before any edits land.
- First contact with an unfamiliar codebase - “give me the tour: where’s auth, what’s the data model, what’s the testing pattern” without any risk of accidental writes.
- Code review - paste a diff (or point at a branch) and ask for findings. No edits, just analysis.
- Architecture discussions - “if we wanted to split this monolith, what would the seams be?” The output is a doc, not a PR.
- Pre-incident dry runs - “walk me through how a rollback would work if the deploy fails” without the rollback actually running.
- Reviewing the agent’s own proposal - when the agent suggests a design, switch to Plan mode to discuss it before letting it implement.
The test: if the right next action is “talk about it,” not “do it,” you want Plan mode.
The stages of a planned task
Section titled “The stages of a planned task”The lifecycle is the same everywhere - switch in, explore, plan, gate, execute - but every stage looks different per tool. Step through one task and switch tools to compare. Pi has no built-in mode, so it isn’t in the stepper; its tab below covers the substitutes.
What the mode blocks, and what it only asks about
Section titled “What the mode blocks, and what it only asks about”“Read-only” is doing different amounts of work in each tool. The implementations sort into four classes of enforcement, and the class only reveals itself in the moment the model reaches for an edit anyway. That moment is the whole reason you switched in.
Blocked by the runtime. Claude Code’s mode blocks Write and Edit for as long as the toggle is on, so a wrong turn fails closed and costs you nothing but the tokens. Bash is gated, not blocked - commands are prompted or classifier-reviewed, and approved commands run. One carve-out matters: in a session where bypass permissions are available, plan mode’s blocks are not enforced - Claude is still instructed to plan rather than edit, but an edit it attempts during planning will run.
Codex has a native Plan mode (/plan, or Shift+Tab), which gathers context and asks questions before implementation. The hard block is a separate control, and the sturdier one: under --sandbox read-only (switchable mid-session with /permissions) the restriction is enforced below the agent, so it doesn’t depend on the session’s other flags.
Gated, not blocked. OpenCode’s plan primary agent is the clearest example of this class. Its current agent docs say it refuses file edits, writes and patches outside its plan directory without prompting, and that shell commands are not restricted by default and follow your permission config. Older docs mapped edits to ask instead, so check which docs line your install follows. Plan’s defaults apply before your top-level permission config and the last matching rule wins, so a global "edit": "allow" also reaches Plan unless you set the plan agent’s permissions directly. The posture is only as read-only as the permission map, which is a different guarantee from a runtime block.
Nothing to block. Copilot’s Plan mode doesn’t execute at all - its whole output is the plan artefact, so there is no edit attempt to intercept. The edits happen later, when you hand the plan to Agent mode, and how hard that is gated is a separate, session-wide setting: chat.permissions.default plus the per-tool auto-approve knobs. Picking Plan from the agents dropdown does not tighten Agent. See Permissions.
Convention only. Pi ships no plan mode, so asking it to write the plan before touching code is a request the model can quietly not honour, not a gate. The plan-mode example under packages/coding-agent/examples/extensions/ in Pi’s repository is what closes that hole: it intercepts edit and bash calls, requires a written plan first, then lifts the gate.
Cursor documents Plan Mode as a research-and-plan workflow, while its public docs do not publish an exhaustive tool allowlist. Treat it as workflow guidance, not as a security boundary. Unverified: its exact runtime blocking behavior depends on the Cursor surface and version. See the Plan Mode announcement and agent modes documentation.
Why this and not…
Section titled “Why this and not…”| You want to… | Reach for | Not |
|---|---|---|
| Have the agent think and propose, but not modify anything | Plan mode | Permissions tuning per call |
| Permanently restrict a worker to read-only | Subagent with read-only tools | Plan mode |
| Block specific dangerous commands while keeping the rest permissive | Permissions / hooks | Plan mode |
| Get a structured plan artifact (file, checklist) | Skill that produces a plan + plan mode | Plan mode alone |
| Pause the agent mid-flow to check approach | Plan mode toggle | Restarting the session |
The line under all of these: plan mode constrains the loop for a session, while subagents and permissions constrain it structurally. Reach for the structural ones when the restriction should outlive the conversation.
How it works in each tool
Section titled “How it works in each tool”Showing: Claude Code pick a tab to change
Press Shift-Tab to toggle Plan mode. Or invoke /plan to enter.
In Plan mode (while bypass permissions is not active):
- Read, search, and grep tools work normally.
- Write and Edit are blocked; Bash is gated - commands are prompted or classifier-reviewed, and approved commands run.
- Claude is instructed to produce a plan, not action.
- Toggle Shift-Tab again (or accept the plan) to drop back into normal mode.
Plan mode is a session toggle, not a separate agent - it modifies the active agent’s permissions for the duration. The optional sandbox adds OS-level Bash isolation; use it with permission rules when the filesystem or network must be contained.
Codex has a /plan command (and Shift+Tab cycles the collaboration mode) that switches the session to Plan mode. For a hard guarantee that nothing is written, combine permission primitives instead:
codex --sandbox read-only --ask-for-approval on-request--sandbox read-only- the agent physically cannot write files or run mutating commands.--ask-for-approval on-request- anything that needs escalation prompts you.
Switching out of this posture mid-session: /permissions opens an interactive picker with presets like Read Only and Auto that applies the change to the running session. Restarting with new flags is the alternative.
OpenCode treats Plan as a primary agent, not a toggle. There are two primary agents shipped:
build- full edit access (the default)plan- read-only with edits gated to ask/deny
Switch between them with the Tab key. Custom primary agents can define their own permission profiles, so you can build a “review” or “audit” primary that lives alongside build and plan.
Because plan-vs-build is a primary agent, not a mode flag, you can have history-preserving toggling: switch into plan, ask the agent to outline an approach, then Tab back to build and execute it - same session, distinct contexts.
Cursor made Plan Mode a first-class mode, separate from Agent - not just a permission flag. It is activated from the mode picker or by pressing Shift+Tab in the chat input (the CLI also has /plan, --plan, and --mode=plan); Cursor may also suggest it for complex tasks. As of 2026-10.
What Plan Mode does:
- Agent asks clarifying questions.
- Researches the codebase for context (read-only at this stage).
- Generates a comprehensive implementation plan as an editable markdown file.
- Plans are saved in your home directory by default; use “Save to workspace” to move one into the repo for sharing.
- User edits the plan inline (add/remove todos, change approach) before clicking to build.
Cursor documents plan-with-one-model, build-with-another as a way to pair a reasoning model for planning with a faster execution model for the build step. Plans can be branched and compared where the installed surface supports those controls. As of 2026-08-07.
Cursor documents Plan Mode as a research-and-plan workflow, but does not publish an exhaustive tool allowlist. Treat its read-only behavior as a workflow expectation, not as a security guarantee.
Copilot Chat in VS Code makes Plan a first-class mode alongside Ask and Agent - pick it from the mode dropdown in the chat input.
The VS Code Chat modes:
- Ask - answer questions, no code edits
- Plan - produce a structured implementation plan (steps, risks, acceptance criteria) without executing
- Agent - autonomous loop: plan, edit files, run tools, iterate until done
Edit mode was deprecated in VS Code 1.110 (February 2026) and has since been folded into Agent; for edit-style behavior, define a custom agent.
Plan mode has its own setting: chat.planAgent.defaultModel. Typical flow is to use it as a pre-flight to Agent mode: write the plan in Plan, then hand it to Agent to execute. Custom agents defined in .agent.md can be configured as planning agents specifically.
This is more structured than a flag-driven plan posture - the mode is part of the IDE chrome, not a runtime toggle on top of a single agent loop.
Copilot cloud agent and Copilot CLI have their own plan behaviours (plan-then-implement inside a PR; an interactive runtime plan toggle in the CLI). Both are out of scope for this IDE-focused tab.
No built-in plan mode. There’s no toggle that flips Pi into a read-only, plan-then-execute posture the way Claude Code’s Shift-Tab or OpenCode’s plan primary agent do.
Ways to get the same discipline:
- Write the plan to a file and ask Pi to draft it before touching code - plain prompting, no special mode required. This is the zero-setup option and works today.
- Install or build a plan-mode extension. The Pi repo’s
examples/extensions/directory includes a plan-mode example demonstrating the pattern via the ExtensionAPI - intercept edit/bash calls, require a written plan first, then lift the gate. - Ask Pi to build one for you. Since extensions are just code Pi can write, describing the plan-mode behavior you want and having the agent implement it as a project extension is a legitimate path, consistent with Pi’s overall “build it from primitives” philosophy.
If plan mode is a hard requirement for your workflow, it’s worth weighing against the effort of assembling the equivalent yourself.
Comparison
Section titled “Comparison”| Aspect | Claude Code | Codex | OpenCode | Cursor | Copilot | Pi |
|---|---|---|---|---|---|---|
| Mechanism | Session toggle (Shift-Tab) | Plan mode (/plan or Shift+Tab), with a read-only sandbox as a separate guardrail |
Primary agent (Tab) | First-class IDE mode (Shift+Tab / dropdown) | First-class IDE mode (agents dropdown) | No built-in - file a plan manually, or via extension/package |
| Mid-session toggle | Yes (Shift-Tab) | Yes (/plan, Shift+Tab; /permissions for the sandbox posture) |
Yes (Tab) | Yes (mode picker / Shift+Tab) | Yes (mode dropdown) | N/A |
| Edit attempts | Blocked by mode | Plan mode is a workflow; blocked by the sandbox under read-only |
Gated to ask/deny | Plan research workflow; exact allowlist is not published | No execution - produces a plan artefact | N/A - nothing blocks edits without an extension |
| Plan artefact | Inline chat output | Inline chat output | Inline chat output | Editable markdown file (location is version- and workspace-dependent) | Structured plan in chat (session-scoped) | A file you ask the agent to write, by convention |
| Custom plan-like profiles | No | Compose your own sandbox and approval flags | Yes (custom primary) | Plan-with-one-model, build-with-another | Custom .agent.md planning agents |
Via extension/package |
| Preserves history on switch | Yes | Yes via /permissions; no if you restart |
Yes | Yes | Yes | N/A |
Where the plan goes when you leave the mode
Section titled “Where the plan goes when you leave the mode”Plan mode is a session-level posture, not a permanent setting: you flip in, get your plan, flip out, execute. If you find yourself never flipping out, what you actually wanted was a read-only subagent or a tighter permissions profile. But what you carry out with you is not the same thing in every tool, and no row above says so.
The plan lives in the window. In Claude Code, Codex, and OpenCode the plan is inline chat output, so it survives exactly as long as the session does. Toggle back with Shift-Tab or Tab and the plan, plus everything the agent read while exploring, is still in context. The Codex caveat is that switching posture by restarting instead of through /permissions doesn’t carry the exploration over - the restart starts cold.
The plan lives in a file. Cursor’s mode can produce an editable markdown plan rather than only chat. The location and save workflow are version- and workspace-dependent, so confirm them before assuming the plan is outside the repo or absent from the diff.
The plan lives until the session ends. Copilot’s structured plan is auto-saved to a session memory file and cleared when the session ends. Treat it as a working document rather than a record: if the plan is worth keeping, copy it into the repo before you close the chat.
Pi is the case where the question doesn’t arise. With no mode, the plan is whatever file you asked the agent to write, and it lives as long as any other file in the repo - the weakest enforcement in the set paired with the most durable artefact.
The lifespan is also what makes the mode cheap or expensive. Exploring, planning, and executing in one session pays for the reading once; a restart pays again for the same files. See the cost profiles in How agents work.
The next multi-file change you hand over, switch in before you type the task rather than after the first wrong diff. Then check one thing in your own tool: does the mode block the edit, or only ask you about it? That answer is the difference between a guardrail and a habit, and it decides how much you can safely stop reading.
Name collisions
Section titled “Name collisions”- “Plan mode” in Claude Code is a toggle. In OpenCode it’s a primary agent. In Codex it’s a native mode (
/plan, Shift+Tab) that you pair with a read-only sandbox if you want a hard block. In Cursor and Copilot it’s a first-class IDE mode with a dedicated picker entry. Always say which. - Claude Code’s
/planisn’t a separate skill - it’s a built-in command that’s just another on-ramp into the same Plan mode as Shift-Tab, optionally seeded with a task (/plan fix the auth bug). Same posture, same artifact, two ways in.