Plan mode: having the AI propose before it acts
Plan mode makes an AI agent investigate and propose before it edits anything. How to turn it on in Claude Code, Codex and Cursor, and how a plan gets approved.
What does an agent do in plan mode?
The agent explores the problem: it reads the relevant files, checks the state of the project and writes a plan with the steps it proposes. It is one phase of the loop of an agent, the one where it thinks before acting, explicitly separated from acting. When the plan is ready, the agent presents it and asks how to proceed.
Claude Code’s documentation sums it up this way: plan mode lets Claude read files and run shell commands to research, then write a proposed plan without editing your source code. Edits stay blocked until you approve the plan. That boundary, reading and proposing versus editing, is what makes the mode useful.
How do you turn it on in each tool?
The three cases below come from each product’s official documentation, checked in October 2026.
| Tool | How to enter | What it produces |
|---|---|---|
| Claude Code | Shift+Tab until the status bar shows ⏸ plan mode on; /plan before a prompt; claude --permission-mode plan; or permissions.defaultMode: "plan" in .claude/settings.json | A plan you approve to start editing |
| Codex | /plan (with optional text on the same line) or Shift+Tab | A plan before implementation; the best-practices guide says Codex gathers context and asks clarifying questions |
| Cursor | Shift+Tab in the agent input | A Markdown file with file paths and code references, which you can edit |
A few details worth knowing. In Claude Code, Shift+Tab cycles through the default, acceptEdits and plan modes (and, when available, bypassPermissions and auto); to leave plan mode without approving anything, press Shift+Tab again. In Codex, /plan is unavailable while the agent is already working. In Cursor, the agent researches the codebase, reviews documentation and asks clarifying questions before drafting the plan, and plans are saved to your home directory by default; the “Save to workspace” button moves them into the project.
Why separate planning from executing?
Because a mistake in direction costs more than a mistake in detail. If the agent decides to rewrite a whole module when a configuration change would do, every later step deepens the error, and the person discovers it when many files are already touched.
Plan mode forces the decision about the path to be made in the open. The person reads the plan, corrects what they do not like, and only then does the agent touch the code. It is an approval of strategy, not of every line, and an early form of human control. It also reduces the need to stop the agent halfway, which is what interrupting and steering an agent describes. Reviewing a five-step plan takes minutes; reviewing the result of forty changes takes much longer, and undoing them longer still.
How is a plan approved?
The approval design matters as much as the mode. In Claude Code, when the plan is ready, the agent presents it and offers three options:
- “Yes, and use auto mode”. Approves and starts auto mode. If that mode is not available in the session, the option reads “Yes, auto-accept edits”.
- “Yes, manually approve edits”. Approves, and the person reviews each edit.
- “No, keep planning”. Stays in plan mode so you can tell the agent what to change.
In addition, Ctrl+G opens the plan in your text editor so you can modify it before the agent continues. In Cursor, the plan can also be edited by hand, including its to-dos, and is built with one click when it is ready.
Those options show a useful design pattern: approve as it is, approve while choosing how much supervision the execution gets, ask for changes without running anything, and edit the plan directly. The option most often forgotten and most worth using is the third: correcting before any file is touched. One important detail: approving the plan leaves plan mode and switches to an editing mode, so the agent starts editing right after. The screen must say clearly what comes next and how much review the changes will get. For the general pattern of asking permission, see action approval and permissions UX for agents.
What is blocked and what can run while planning?
In Claude Code, reading files and running shell commands to explore is allowed; editing source code is blocked. Terminal commands have their own rules. According to the documentation, the first matching case applies:
- Interactive terminal with bypass permissions available: planning is not strictly enforced; only explicit “ask” rules and critical-path removals still prompt.
- Auto mode available and
useAutoModeDuringPlanon (the default): a classifier reviews shell commands instead of prompting you; approved ones run and rejected ones are blocked. - Auto mode unavailable, or
useAutoModeDuringPlanoff: commands outside the built-in read-only set ask for approval.
The design lesson: a plan mode that says “it changes nothing” but lets commands run that modify something deceives the person. In a custom interface, state what the agent can do in that phase and ask permission for everything else. The Codex and Cursor documentation consulted does not detail which commands run during planning, so test it in your version before relying on it.
Example
Illustrative example: a team wants to change the theme system of its application, which is currently spread across twenty files. Before touching anything, they turn on plan mode. The agent reads the files and proposes: “Centralize the colors in a single tokens file, migrate four components first, then the rest. Risk: the charts component uses fixed colors that would need review”.
The designer asks for a change: “Migrate the invoices component first, not the charts one, which has no tests”. She edits the plan, approves it with “Yes, manually approve edits” and reviews each edit of the first batch. The change the team feared is made in two batches, with the underlying decision taken at the start and not halfway through the task.
When should you NOT use plan mode?
- For small, well-known changes. Fixing a typo or changing a color does not need a plan; the approval step only adds friction.
- When the person needs to see the result to decide. In visual exploration, a quick prototype is sometimes more useful than a written plan; there, previewing the changes helps.
- When planning becomes a task of its own. If the plan takes longer than the work, the mode is being misapplied.
Common mistakes
- Using plan mode for everything, including trivial tasks.
- Approving plans without reading them because the step feels like a formality.
- Believing plan mode never runs anything, when some commands do run.
- Not using the option to ask for changes without running anything.
- Approving the plan and losing sight of the mode change that results.