[{"data":1,"prerenderedAt":56},["ShallowReactive",2],{"blog-claude-code-plan-mode":3,"blog-related-claude-code-plan-mode":39},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-plan-mode","Plan mode in Claude Code: think before it touches a file","How to start plan mode in Claude Code, read and edit the plan, pick the approval option, and when planning first saves you from a big wrong diff.","Getting started","getting-started","claude code plan mode","2026-11-17",5,"Plan mode makes Claude Code read your project and propose a plan without changing any source file. Edits stay blocked until you approve. Start it with `Shift+Tab` until the status bar says `⏸ plan mode on`, with `claude --permission-mode plan`, or by typing `\u002Fplan` before a prompt. It is the cheapest way to catch a wrong approach before it becomes a forty-file diff.\n\n## How do you turn plan mode on?\n\nThree ways, all equivalent:\n\n```sh\nclaude --permission-mode plan\n```\n\nOr, inside a session, press `Shift+Tab` to cycle through the permission modes. The cycle goes `default`, `acceptEdits`, `plan`, and the status bar shows `⏸ plan mode on` when you land on it. Or type the command with a description, which enters plan mode and starts on the task straight away:\n\n```text\n\u002Fplan fix the auth bug where refresh tokens are never rotated\n```\n\nTo make it the standing default, set `permissions.defaultMode` to `plan` in a settings file. All the modes are covered in [permission modes explained](\u002Fblog\u002Fclaude-code-permission-modes).\n\n## What does Claude do in plan mode?\n\nIt reads files, runs shell commands to explore, and writes a plan. It does not edit your source until you approve. So a good plan-mode prompt asks for investigation plus a proposal:\n\n```text\nWe need rate limiting on the public API. Read how middleware is wired in\nsrc\u002Fserver\u002F, look at how auth is done, and propose a plan: which files\nchange, in what order, and how we test it. Ask me anything that is unclear.\n```\n\nNotice what that prompt contains: the goal, where to look, the shape of the answer, and permission to ask questions. Plans get better when Claude can ask, and worse when it has to guess at requirements.\n\n## How do you approve, edit or reject the plan?\n\nWhen the plan is ready, Claude asks how to proceed. The options you will see:\n\n- **Yes, and use auto mode.** Approves and starts editing in auto mode. If auto mode is not available to your session, this reads \"Yes, auto-accept edits\". If you started with bypass permissions enabled, it offers to switch to that instead.\n- **Yes, manually approve edits.** Approves the plan and keeps asking before each edit.\n- **No, keep planning.** Stays in plan mode so you can say what to change.\n\nThere is also an optional setting, `showClearContextOnPlanAccept`, that adds a first option approving the plan and clearing the planning context. That is handy because the exploration that produced the plan often filled the context window with file reads you no longer need.\n\nTwo shortcuts worth knowing. Press `Ctrl+G` to open the proposed plan in your default text editor, change it, and then let Claude continue: editing the plan yourself is faster than arguing about it. And if you want to leave plan mode without approving, press `Esc` first and then `Shift+Tab`, because at the approval prompt `Shift+Tab` approves the plan.\n\nOn approval, the session switches to the permission mode of the option you chose and starts editing. Claude Code also gives the session a title based on the plan, unless you have already named it.\n\n## When is plan mode worth it?\n\nUse it when the cost of going the wrong way is high:\n\n- A change that spans several files or layers (a schema change plus the code that reads it).\n- Code you do not know yet. The plan is also your tour of how it works.\n- A refactor where the order of steps matters.\n- A vague request: planning forces the missing questions into the open.\n- Anything you will hand to a teammate or review in a pull request; the plan is the description.\n\nSkip it when you can describe the diff in one sentence (\"rename `getUser` to `fetchUser` everywhere\", \"fix this typo\"). Planning a one-line change is overhead.\n\n## How do you review a plan well?\n\nRead it as you would read a design proposal:\n\n1. **Is it the right problem?** Check the first lines against what you asked.\n2. **Does it touch only what it should?** A plan that mentions files you did not expect usually found a dependency, or misread the task.\n3. **Is there a way to verify?** A good plan names the tests or commands that prove the change works. If it does not, say so and send it back with \"No, keep planning\".\n4. **Are the steps ordered so each leaves the project working?** Small steps that each pass tests are easier to review and to undo.\n5. **What did it leave out?** Ask \"what are the risks and what did you decide not to do?\"\n\nThen pick the approval option that matches your trust: manual approval for risky changes, auto-accept for contained ones.\n\n## Where does the plan live, and can it run headless?\n\nThe plan files of the current session are stored under `~\u002F.claude\u002Fplans\u002F`, or in the directory set by the `plansDirectory` setting. Claude Code treats that folder as protected, so you should not need to touch it by hand. Nothing in it replaces committed documentation: if the plan is worth keeping, ask Claude to put the final version in your repository, for instance in `docs\u002F`.\n\nThe same flag works with `claude -p` for non-interactive use, which is useful for generating a plan in a script or a CI job and reading it before anything runs for real:\n\n```sh\nclaude -p --permission-mode plan \"plan the migration to the new payments client\"\n```\n\n## A habit that pays off\n\nCombine the two ends of the workflow: plan first, approve into a permissive mode, then review the diff, which is much smaller than it would have been without a plan. If you are still getting started, the [beginner's guide](\u002Fblog\u002Fclaude-code-beginners-guide) puts this in order, and [how to prompt Claude Code](\u002Fblog\u002Fclaude-code-prompting-tips) covers how to phrase the request.\n\n## In Relais\n\nRelais shows Claude Code's plans as their own card in the conversation, next to the inline approval cards for edits, so you read and answer the plan in the chat. Plan is one of the four permission modes in the composer's picker, and a session template or a workflow step can start in plan mode. See [features](\u002Ffeatures).","\u003Cp>Plan mode makes Claude Code read your project and propose a plan without changing any source file. Edits stay blocked until you approve. Start it with \u003Ccode>Shift+Tab\u003C\u002Fcode> until the status bar says \u003Ccode>⏸ plan mode on\u003C\u002Fcode>, with \u003Ccode>claude --permission-mode plan\u003C\u002Fcode>, or by typing \u003Ccode>\u002Fplan\u003C\u002Fcode> before a prompt. It is the cheapest way to catch a wrong approach before it becomes a forty-file diff.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-turn-plan-mode-on\">\u003Ca class=\"anchor\" href=\"#how-do-you-turn-plan-mode-on\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you turn plan mode on?\u003C\u002Fh2>\n\u003Cp>Three ways, all equivalent:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude --permission-mode plan\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Or, inside a session, press \u003Ccode>Shift+Tab\u003C\u002Fcode> to cycle through the permission modes. The cycle goes \u003Ccode>default\u003C\u002Fcode>, \u003Ccode>acceptEdits\u003C\u002Fcode>, \u003Ccode>plan\u003C\u002Fcode>, and the status bar shows \u003Ccode>⏸ plan mode on\u003C\u002Fcode> when you land on it. Or type the command with a description, which enters plan mode and starts on the task straight away:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>\u002Fplan fix the auth bug where refresh tokens are never rotated\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>To make it the standing default, set \u003Ccode>permissions.defaultMode\u003C\u002Fcode> to \u003Ccode>plan\u003C\u002Fcode> in a settings file. All the modes are covered in \u003Ca href=\"\u002Fblog\u002Fclaude-code-permission-modes\">permission modes explained\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"what-does-claude-do-in-plan-mode\">\u003Ca class=\"anchor\" href=\"#what-does-claude-do-in-plan-mode\" aria-label=\"Link to this section\">#\u003C\u002Fa>What does Claude do in plan mode?\u003C\u002Fh2>\n\u003Cp>It reads files, runs shell commands to explore, and writes a plan. It does not edit your source until you approve. So a good plan-mode prompt asks for investigation plus a proposal:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>We need rate limiting on the public API. Read how middleware is wired in\nsrc\u002Fserver\u002F, look at how auth is done, and propose a plan: which files\nchange, in what order, and how we test it. Ask me anything that is unclear.\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Notice what that prompt contains: the goal, where to look, the shape of the answer, and permission to ask questions. Plans get better when Claude can ask, and worse when it has to guess at requirements.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-approve-edit-or-reject-the-plan\">\u003Ca class=\"anchor\" href=\"#how-do-you-approve-edit-or-reject-the-plan\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you approve, edit or reject the plan?\u003C\u002Fh2>\n\u003Cp>When the plan is ready, Claude asks how to proceed. The options you will see:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Yes, and use auto mode.\u003C\u002Fstrong> Approves and starts editing in auto mode. If auto mode is not available to your session, this reads &quot;Yes, auto-accept edits&quot;. If you started with bypass permissions enabled, it offers to switch to that instead.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Yes, manually approve edits.\u003C\u002Fstrong> Approves the plan and keeps asking before each edit.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>No, keep planning.\u003C\u002Fstrong> Stays in plan mode so you can say what to change.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>There is also an optional setting, \u003Ccode>showClearContextOnPlanAccept\u003C\u002Fcode>, that adds a first option approving the plan and clearing the planning context. That is handy because the exploration that produced the plan often filled the context window with file reads you no longer need.\u003C\u002Fp>\n\u003Cp>Two shortcuts worth knowing. Press \u003Ccode>Ctrl+G\u003C\u002Fcode> to open the proposed plan in your default text editor, change it, and then let Claude continue: editing the plan yourself is faster than arguing about it. And if you want to leave plan mode without approving, press \u003Ccode>Esc\u003C\u002Fcode> first and then \u003Ccode>Shift+Tab\u003C\u002Fcode>, because at the approval prompt \u003Ccode>Shift+Tab\u003C\u002Fcode> approves the plan.\u003C\u002Fp>\n\u003Cp>On approval, the session switches to the permission mode of the option you chose and starts editing. Claude Code also gives the session a title based on the plan, unless you have already named it.\u003C\u002Fp>\n\u003Ch2 id=\"when-is-plan-mode-worth-it\">\u003Ca class=\"anchor\" href=\"#when-is-plan-mode-worth-it\" aria-label=\"Link to this section\">#\u003C\u002Fa>When is plan mode worth it?\u003C\u002Fh2>\n\u003Cp>Use it when the cost of going the wrong way is high:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>A change that spans several files or layers (a schema change plus the code that reads it).\u003C\u002Fli>\n\u003Cli>Code you do not know yet. The plan is also your tour of how it works.\u003C\u002Fli>\n\u003Cli>A refactor where the order of steps matters.\u003C\u002Fli>\n\u003Cli>A vague request: planning forces the missing questions into the open.\u003C\u002Fli>\n\u003Cli>Anything you will hand to a teammate or review in a pull request; the plan is the description.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Skip it when you can describe the diff in one sentence (&quot;rename \u003Ccode>getUser\u003C\u002Fcode> to \u003Ccode>fetchUser\u003C\u002Fcode> everywhere&quot;, &quot;fix this typo&quot;). Planning a one-line change is overhead.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-review-a-plan-well\">\u003Ca class=\"anchor\" href=\"#how-do-you-review-a-plan-well\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you review a plan well?\u003C\u002Fh2>\n\u003Cp>Read it as you would read a design proposal:\u003C\u002Fp>\n\u003Col>\n\u003Cli>\u003Cstrong>Is it the right problem?\u003C\u002Fstrong> Check the first lines against what you asked.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Does it touch only what it should?\u003C\u002Fstrong> A plan that mentions files you did not expect usually found a dependency, or misread the task.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Is there a way to verify?\u003C\u002Fstrong> A good plan names the tests or commands that prove the change works. If it does not, say so and send it back with &quot;No, keep planning&quot;.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Are the steps ordered so each leaves the project working?\u003C\u002Fstrong> Small steps that each pass tests are easier to review and to undo.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>What did it leave out?\u003C\u002Fstrong> Ask &quot;what are the risks and what did you decide not to do?&quot;\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>Then pick the approval option that matches your trust: manual approval for risky changes, auto-accept for contained ones.\u003C\u002Fp>\n\u003Ch2 id=\"where-does-the-plan-live-and-can-it-run-headless\">\u003Ca class=\"anchor\" href=\"#where-does-the-plan-live-and-can-it-run-headless\" aria-label=\"Link to this section\">#\u003C\u002Fa>Where does the plan live, and can it run headless?\u003C\u002Fh2>\n\u003Cp>The plan files of the current session are stored under \u003Ccode>~\u002F.claude\u002Fplans\u002F\u003C\u002Fcode>, or in the directory set by the \u003Ccode>plansDirectory\u003C\u002Fcode> setting. Claude Code treats that folder as protected, so you should not need to touch it by hand. Nothing in it replaces committed documentation: if the plan is worth keeping, ask Claude to put the final version in your repository, for instance in \u003Ccode>docs\u002F\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>The same flag works with \u003Ccode>claude -p\u003C\u002Fcode> for non-interactive use, which is useful for generating a plan in a script or a CI job and reading it before anything runs for real:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude -p --permission-mode plan &quot;plan the migration to the new payments client&quot;\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2 id=\"a-habit-that-pays-off\">\u003Ca class=\"anchor\" href=\"#a-habit-that-pays-off\" aria-label=\"Link to this section\">#\u003C\u002Fa>A habit that pays off\u003C\u002Fh2>\n\u003Cp>Combine the two ends of the workflow: plan first, approve into a permissive mode, then review the diff, which is much smaller than it would have been without a plan. If you are still getting started, the \u003Ca href=\"\u002Fblog\u002Fclaude-code-beginners-guide\">beginner&#39;s guide\u003C\u002Fa> puts this in order, and \u003Ca href=\"\u002Fblog\u002Fclaude-code-prompting-tips\">how to prompt Claude Code\u003C\u002Fa> covers how to phrase the request.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>Relais shows Claude Code&#39;s plans as their own card in the conversation, next to the inline approval cards for edits, so you read and answer the plan in the chat. Plan is one of the four permission modes in the composer&#39;s picker, and a session template or a workflow step can start in plan mode. See \u003Ca href=\"\u002Ffeatures\">features\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33,36],{"id":16,"text":17},"how-do-you-turn-plan-mode-on","How do you turn plan mode on?",{"id":19,"text":20},"what-does-claude-do-in-plan-mode","What does Claude do in plan mode?",{"id":22,"text":23},"how-do-you-approve-edit-or-reject-the-plan","How do you approve, edit or reject the plan?",{"id":25,"text":26},"when-is-plan-mode-worth-it","When is plan mode worth it?",{"id":28,"text":29},"how-do-you-review-a-plan-well","How do you review a plan well?",{"id":31,"text":32},"where-does-the-plan-live-and-can-it-run-headless","Where does the plan live, and can it run headless?",{"id":34,"text":35},"a-habit-that-pays-off","A habit that pays off",{"id":37,"text":38},"in-relais","In Relais",[40,45,51],{"slug":41,"title":42,"description":43,"category":7,"categoryId":8,"keyword":44,"date":10,"minutes":11},"claude-code-beginners-guide","Claude Code for beginners: install, first session, habits","Install Claude Code, run your first session and learn the habits that matter: specific prompts, plan before edit, CLAUDE.md, small commits, a clean context.","claude code for beginners",{"slug":46,"title":47,"description":48,"category":7,"categoryId":8,"keyword":49,"date":10,"minutes":50},"claude-code-hooks","Claude Code hooks: run a script on every tool call","Claude Code hooks run your own script before or after a tool call. Learn the config format, exit codes and three working examples you can paste today.","claude code hooks",6,{"slug":52,"title":53,"description":54,"category":7,"categoryId":8,"keyword":55,"date":10,"minutes":11},"claude-code-permission-modes","Claude Code permission modes explained (and when to use each)","Default, acceptEdits, plan, auto, dontAsk and bypassPermissions: what each Claude Code permission mode allows, how to switch, and which one fits which job.","claude code permission modes",1794931098788]