What is plan mode? Claude Code, Codex, Cursor and Grok Build
By Flavio
Plan mode makes a coding agent research and propose a plan before it edits code. How it works in Claude Code, Codex, Cursor and Grok Build, and when to use it.
Plan mode is a mode where a coding agent researches your codebase and writes a plan for a change, then waits for your approval before it edits your code. You review the approach while it’s still cheap to change.
How plan mode works
You switch to plan mode and describe what you want. The agent reads the relevant files and may ask you a few questions. Then it writes a plan: which files it will change, in what order, and how it will check the result.
You read the plan. If something is off, you ask for changes and the agent revises it. When you approve, the agent leaves plan mode and starts implementing.
Reviewing at this point is cheap. A wrong assumption in a plan takes a sentence to fix, while the same assumption spread across twelve edited files takes a revert and a second attempt.
Be careful with the idea that plan mode is read-only, because it isn’t the same in every tool. Claude Code runs shell commands while it explores. Grok Build blocks edit tools, but its shell commands still follow your permission mode. The details are below.
Plan mode in each tool
| Claude Code | Codex | Cursor | Grok Build | |
|---|---|---|---|---|
| Switch to it | Shift+Tab, or start a prompt with /plan | /plan or Shift+Tab | Shift+Tab, or the mode picker | Shift+Tab, or /plan |
| Start a session in it | claude --permission-mode plan | Not documented | --plan in the Cursor CLI | Not documented |
| Where the plan goes | A plan file, in ~/.claude/plans by default | Not documented | Your home directory, until you save it to the workspace | A session plan file |
| Approve it | Pick an option in the approval menu | Not documented | Click Build | Press a in the plan preview |
Claude Code
In Claude Code, plan mode is one of the permission modes. Claude reads files and runs shell commands to explore, and writes a plan, but doesn’t edit your source.
Shift+Tab cycles through the modes until the status bar shows plan mode. You can also put /plan in front of a single prompt, or start a session with claude --permission-mode plan. To make plan mode the default for a project, set defaultMode to plan in .claude/settings.json.
During planning, the built-in Plan subagent gathers context. Shell commands outside a read-only set either go through the auto mode classifier, when it’s available, or ask for your approval.
When the plan is ready, Claude shows an approval menu. You can approve and let Claude edit with fewer prompts, approve and review each edit yourself, or keep planning and say what to change. Press Ctrl+G to open the plan in your text editor and change it before Claude proceeds. Plans are saved as files in ~/.claude/plans, and the plansDirectory setting moves them into your project.
See plan mode in the Claude Code docs.
OpenAI Codex
In Codex, type /plan to switch the chat into plan mode, or add the request on the same line, like /plan Propose a migration plan for this service. The best practices page also lists Shift+Tab as a toggle. Codex gathers context, asks clarifying questions and builds the plan before implementation.
/plan isn’t available while Codex is already working on something. The plan_mode_reasoning_effort setting in config.toml sets how hard the model thinks while planning.
The docs don’t say whether plan mode technically blocks edits. When you want a guarantee, switch to the read-only mode with /permissions, which the docs suggest for chatting or planning without changes. When Goal mode is available, the docs suggest following the plan with /goal to set a persistent goal.
See the Codex slash commands and the Codex prompting guide.
Cursor
In Cursor, press Shift+Tab in the chat input to rotate to Plan, or pick it from the mode picker. Cursor also suggests plan mode when your prompt sounds like a complex task. In the Cursor CLI, use /plan, or start with --plan.
The agent researches the codebase, asks clarifying questions and writes a plan you can edit, in the chat or as a Markdown file. Plans are saved in your home directory by default, and “Save to workspace” moves one into your project so the team can read it. When the plan looks right, click Build.
Plan mode is different from Ask mode, which Cursor describes as read-only exploration without making changes. See the Cursor plan mode docs.
Grok Build
In Grok Build, /plan turns on plan mode for your next prompt, and /plan <description> starts planning right away. From normal mode, one press of Shift+Tab lands on plan mode. Grok can also enter plan mode on its own when a task looks ambiguous.
Until you approve, the only file the agent can edit is the session plan file. Other edit tools are rejected, even in auto or always-approve mode. Shell commands, reads and MCP tools still follow your permission mode.
When the plan is done, a preview opens. Press a to approve and start building, s to request changes, c to comment on a line, or q to quit plan mode. /view-plan reopens a saved plan. See the Grok Build plan mode docs.
Details checked against each vendor’s documentation in October 2026.
A real example
Let’s plan a small feature on a blog built with Markdown posts. This prompt works as written in Claude Code, Codex, Grok Build and the Cursor CLI:
/plan Show a "Last updated" date on every post page. Posts are Markdown files in src/posts/ with an optional updated: field in the frontmatter. Use the publish date when updated: is missing. Don't change the RSS feed.Notice the prompt says what to leave alone. Plans tend to grow, and “Don’t change the RSS feed” keeps this one small.
A useful plan for this lists the layout file that renders the post header, how the date gets formatted, and a check, like building the site and opening one post with an updated: field and one without.
When you review it, check which files it plans to touch, whether its assumptions about your code are true, and how it will check the result. Ask for changes until you’d be happy to see that diff, then approve.
If the implementation still goes wrong, the Cursor docs suggest reverting, making the plan more specific and running it again, which is often faster than fixing a half-done change.
When to use plan mode
Use it when there’s more than one reasonable way to do the change, when it touches many files, or when you aren’t sure the agent understands the code. The Grok Build docs list ambiguous architecture, unclear requirements and high-impact restructures. The Claude Code docs frame it as avoiding expensive rework when the first direction is wrong.
Skip it for changes with one obvious path. The Grok Build docs name clear one-path changes, obvious bug fixes, renames and formatting. For pure research with no change in mind, an explore subagent is a better fit than a plan.
Pitfalls
Plan mode isn’t a sandbox. Claude Code runs shell commands while it explores, and Grok Build’s docs warn that bash can still write files through redirection. In interactive Claude Code sessions where bypass permissions are available, plan mode’s blocks aren’t enforced at all. If the agent must not change anything, use a read-only permission mode or sandbox.
In Claude Code, approving a plan also switches the session to a permission mode, and some of those modes edit without asking. Read the option before you pick it.
Planning fills the context window. Exploring a big codebase reads a lot of files, and the Claude Code settings docs warn that planning can use a lot of context. Claude Code has an opt-in setting, showClearContextOnPlanAccept, that adds an approval option to clear the context and implement from the plan alone.
In Grok Build, subagents aren’t held back by the parent’s plan mode. They inherit the permission mode, so a subagent can edit files while the main session is still planning.
Long plans are hard to review properly. If a plan is too long to read carefully, ask for a shorter one or split the work into two changes.
Related on flaviocopes.com
- How to use Grok Build has a section on plan mode for larger changes and on the limits of its edit gate.
- How to use the Codex CLI shows planning bigger changes before Codex writes code.
- AI coding agent context: how to document project decisions keeps the decisions a plan relies on in files the agent reads next time.
- Architecture Dissector is my Mac app that draws an app’s components, workflows and data from maps your agents write. It makes it easier to see which parts of an app a plan touches.
Related glossary entries
- Permission modes: Permission modes decide what a coding agent can do without asking. The modes in Claude Code, Codex, Cursor and Grok Build, and what YOLO mode really skips.
- Subagents: A subagent is a helper your coding agent starts with its own context window. How subagents work in Claude Code, Codex, Cursor and Grok Build.
- Context window: The context window is everything a coding agent can see at once. How to check it, free it and keep it small in Claude Code, Codex, Cursor and Grok Build.
Want me to talk about your product? You can sponsor this site.