Plan mode / read-only agent
What plan mode is
Section titled “What plan mode is”Plan mode is a posture: 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 — but each tool implements it differently: a toggle in Claude Code, a flag combination in Codex, a separate primary agent in opencode, and — newer and more structured — a first-class IDE mode in Cursor 2.0 and in Copilot Chat (sitting alongside Ask, Edit, and Agent).
Why you’d want one
Section titled “Why you’d want one”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.
That’s the gap plan mode closes. In plan mode the agent literally can’t edit, so it has to put the plan in front of you first. You read it, push back, adjust, and only then drop out of plan mode to execute. The same conversation, but with the alignment step put back where it belongs — before the writes, not after.
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.
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 |
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.
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:
- 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.
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.
Unverified: the precise tool allowlist inside Plan Mode (read-only vs. limited write) is not exhaustively documented.
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.
Comparison
Section titled “Comparison”| Aspect | Claude Code | Codex | opencode | Cursor | Copilot |
|---|---|---|---|---|---|
| Mechanism | Session toggle (Shift-Tab) | Sandbox + approval combo | Primary agent (Tab) | First-class IDE mode (Shift+Tab / dropdown) | First-class IDE mode (mode dropdown) |
| Mid-session toggle | Yes (Shift-Tab) | Yes (/permissions picker) | Yes (Tab) | Yes (mode picker / Shift+Tab) | Yes (mode dropdown) |
| Edit attempts | Blocked by mode | Blocked by sandbox | Gated to ask/deny | Read-only research; plan emitted as editable markdown | No execution — produces a plan artefact |
| Plan artefact | Inline chat output | Inline chat output | Inline chat output | Editable markdown file (home dir or workspace) | Structured plan in chat (steps, risks, acceptance) |
| Custom plan-like profiles | No | Compose your own flags | Yes (custom primary) | Plan-with-one-model, build-with-another | Custom .agent.md planning agents |
| Preserves history on switch | Yes | N/A (restart) | Yes | Yes | Yes |
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.
- The Claude Code
/planskill is different from Shift-Tab Plan mode —/planis a skill that asks Claude to outline a plan; Plan mode is the permission posture. They’re often used together.