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, Edit, and non-read Bash for as long as the toggle is on, so the tool call cannot land even if the model tries. Codex composes the same posture out of permission primitives: under --sandbox read-only the agent physically cannot write files or run mutating commands. In both, a wrong turn fails closed and costs you nothing but the tokens.
Gated, not blocked. OpenCode’s plan primary agent maps edits to ask/deny rather than refusing them. A proposed edit surfaces for your approval instead of executing; deny it and the agent keeps planning, approve it and the edit lands mid-plan. The posture is only as read-only as your answers, which is a different guarantee from the one above.
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 mode 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 in Pi’s examples/extensions/ is what closes that hole: it intercepts edit and bash calls, requires a written plan first, then lifts the gate.
Cursor belongs with the first class in practice and with a caveat on paper: 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. 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”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, Edit, and Bash (non-read commands) are blocked.
- 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 doesn’t have a single “plan mode” toggle. The same posture is reached by combining permission primitives:
codex --sandbox read-only --ask-for-approval untrusted--sandbox read-only- the agent physically cannot write files or run mutating commands.--ask-for-approval untrusted- 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 2.0 made Plan Mode a first-class mode, separate from Agent - not just a permission flag. Activated by Shift+Tab in the chat input, via the mode dropdown, or /plan in the CLI. The mode picker also includes Ask Mode (read-only Q&A), Agent Mode (default, full execution), and Debug Mode (added later).
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 default to the user’s home directory; “Save to workspace” moves them to the repo for sharing.
- User edits the plan inline (add/remove todos, change approach) before clicking to build.
Cursor 2.0 also added plan-with-one-model, build-with-another - pair a frontier reasoning model for planning with a faster execution model for the build step. Plans can be branched and compared.
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, Edit, and Agent - pick it from the mode dropdown in the chat input.
The four VS Code Chat modes:
- Ask - answer questions, no code edits
- Edit - apply described edits across selected files inline
- Plan - produce a structured implementation plan (steps, risks, acceptance criteria) without executing
- Agent - autonomous loop: plan, edit files, run tools, iterate until done
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 Coding 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) | Sandbox + approval combo | Primary agent (Tab) | First-class IDE mode (Shift+Tab / dropdown) | First-class IDE mode (mode dropdown) | No built-in - file a plan manually, or via extension/package |
| Mid-session toggle | Yes (Shift-Tab) | Yes (/permissions picker) | Yes (Tab) | Yes (mode picker / Shift+Tab) | Yes (mode dropdown) | N/A |
| Edit attempts | Blocked by mode | Blocked by sandbox | 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 (home dir by default) | Structured plan in chat (session-scoped) | A file you ask the agent to write, by convention |
| Custom plan-like profiles | No | Compose your own 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 is the only tool in scope whose mode emits a file rather than chat: an editable markdown plan, defaulting to your home directory. That is outside the repo, invisible to your teammates, and in nobody’s diff until you use “Save to workspace” to move it in. Reviewable in a pull request, then, but only if you move it deliberately.
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 an emergent combination of flags. 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.