Last updated 13 October 2026
When to use planning mode in Claude Code
Large refactors demand architectural oversight
Running a command like claude in a complex repository often leads to immediate action. You might ask for a new feature and watch the terminal start writing files before you have even agreed on the directory structure. This rapid execution works well for small bug fixes or unit tests. However, when you are restructuring a whole module or changing a core database schema, you need a strategy first. Blindly letting an agent edit your codebase can result in broken dependencies that take longer to fix than the original task.
Planning mode provides the friction you need to ensure the agent understands the full scope of a change. Instead of jumping straight to the Edit tool, the agent outlines its intended steps. You see which files it wants to modify and which new ones it intends to create. This architectural pause prevents the agent from going down a rabbit hole of incorrect assumptions. It gives you the chance to correct a bad design choice before a single line of code is committed to disk.
Toggle plan mode with the interface
You enter planning mode by pressing Shift+Tab inside an active claude session. This cycles through the available permission levels until you reach the plan label. In this state, the agent operates under a specific constraint where it cannot modify your environment. It can still use tools like Read, Glob, and Grep to gather information about your project. It will look at your file structure and read relevant files to understand the existing logic, but it will not use Write or Bash to change anything.
This mode is the safest way to explore a large codebase. You can ask the agent to explain how a specific service works or to propose a refactor for a legacy component. Because you are in plan mode, you do not have to worry about accidental file deletions or destructive shell commands. The agent knows it is restricted to thinking and reading. It will present a roadmap of what it would do if it had full permissions. You can then review this roadmap and provide feedback to refine the approach.
Strategic use of CLAUDE.md for better plans
The quality of the plan you receive depends heavily on the instructions you have provided. The CLAUDE.md file in your repository root is the primary source of truth for project-specific rules. If you have specific naming conventions or architectural patterns, you must document them there. When you trigger a plan, the agent reads these instructions to ensure its proposal aligns with your existing standards. You can also place a CLAUDE.md file in a subdirectory to provide more granular guidance for a specific part of the tree.
For example, if your backend uses a specific pattern for service injectors, mention this in your root instructions. When you ask for a new service in plan mode, the agent will include those patterns in its roadmap. This prevents the need for manual corrections later in the process. If the agent proposes something that violates your project style, you can simply tell it to update the plan. This iterative feedback loop is much faster than undoing actual file changes. You stay in control of the high-level design without getting bogged down in the syntax of every file.
Transitioning from strategy to execution
Once you are satisfied with the roadmap provided in plan mode, you need to switch back to an execution mode. Press Shift+Tab again to move to default or acceptEdits. In default mode, the agent will ask for your permission before it uses tools like Write or Bash. This is usually the best next step after a plan. You can tell the agent to proceed with the plan it just generated. It will then start going through the steps it outlined, and you can approve each individual change as it happens.
If you are very confident in the plan and the agent ability to execute it, you might choose acceptEdits. This mode allows the agent to apply file changes without asking for permission every time, though it will still pause for potentially dangerous shell commands. This is useful for large, repetitive refactors that you have already vetted in the planning phase. Always remember that you can interrupt the process at any time by pressing the Escape key. If you see the agent deviating from the agreed plan, hitting Escape twice will let you go back to an earlier message and redirect the conversation.
Managing session context during long planning sessions
Lengthy discussions about architecture can quickly fill the context window of your session. As you refine a plan and ask more questions, the agent has to track more information. Eventually, the performance might degrade or the costs might increase. You can check the current status of your spend and token usage by typing /cost or /usage inside the terminal. If the conversation history is becoming too long, the /compact command is your best tool. It summarizes the session so far and frees up space in the context window.
Using /compact is particularly important before you move from the planning phase to the execution phase. A clean summary of the plan is often more effective for the agent than a long, rambling history of your debate. The summary keeps the core goals and the final roadmap in focus while discarding the discarded ideas. This ensures that when the agent starts writing code, it follows the final version of the plan rather than getting confused by earlier suggestions. You can also use /clear if you want to start fresh in the same directory but keep the same terminal window.
Handling multiple concurrent architectural tracks
Developers often find themselves working on several complex refactors across different branches or repositories. Managing these various planning sessions in a single terminal window can lead to confusion. This is where a tool like adhdTerminal becomes useful for a professional workflow. It allows you to run many claude sessions side by side on a single wall of tiles. You can have one tile dedicated to planning a database migration and another tile for refactoring a frontend component.
Each tile in adhdTerminal shows the state of the session, so you can see at a glance which plan is waiting for your input. Because the app remembers the position and session of every tile, you can restart your computer without losing the context of your architectural discussions. This setup is especially helpful when you are using the plan mode across multiple microservices. You can compare the roadmaps generated in different tiles to ensure they are compatible. This visual overview reduces the mental load of switching between different terminal tabs and trying to remember which session holds which plan.
Permissions and local configuration overrides
Your control over what the agent can do is managed through various settings files. The global configuration resides in ~/.claude/settings.json, while project-specific settings are in .claude/settings.json. If you have personal preferences that you do not want to track in the main repository, you can use .claude/settings.local.json. These files allow you to define which tools require explicit permission and which can be bypassed. For example, you can set the permissions key to always require approval for Bash while allowing Read to happen automatically.
When you are in plan mode, these permission settings are still respected, but the mode itself provides an extra layer of safety. The agent understands that its primary goal is to generate a proposal. If you find yourself frequently using planning mode because you are afraid of the agent making mistakes, it might be time to adjust your settings.json. You can limit the tools available to the agent or change the default permission mode. This customization ensures that the agent works in a way that feels safe and predictable for your specific development style.
Using subagents for specialized planning tasks
Sometimes a project is too large for a single general purpose agent to plan effectively. You can create specialized subagents by adding markdown files to the .claude/agents directory. These subagents can have their own specific instructions and areas of expertise. When you are in a session, you can use the /agents command to see what is available. You can then delegate specific parts of your plan to these specialized subagents.
For instance, you might have an agent specifically for security audits or API design. You can ask your main claude session to consult the API subagent for a roadmap of a new endpoint. This modular approach to planning keeps the main conversation focused while leveraging specific expertise. The subagent will provide a plan for its domain, which the main agent can then integrate into the larger project strategy. This is a powerful way to handle complex systems where different layers require different architectural rules.
Integration with mobile for remote planning
There are times when you start a long planning process at your desk but need to step away. The adhdTerminal system includes a free iPhone app that mirrors your wall of tiles over an end-to-end encrypted link. This allows you to check the progress of a planning task or respond to a prompt while you are away from your workstation. You can read the roadmap the agent has generated and send the next task or a correction directly from your phone.
This flexibility is useful for developers who need to keep projects moving during gaps in their schedule. If you are waiting for a plan to be finalized or for the agent to finish a large reading task, you can monitor the tile from your mobile device. You can see if the agent is working, waiting for you, or done. This ensures that you are never the bottleneck in your own development process. You can approve a plan from your phone and have the agent start the execution phase so that the work is finished by the time you return to your computer.
Questions people ask
How do I force the agent to only use the planning mode?
You can change the mode by pressing Shift+Tab inside a session. While you cannot permanently lock a session into plan mode via settings, the interface will stay in the mode you select until you manually change it again or restart the session.
Can I save a plan to a file for later use?
Yes, you can use the /export command to save the entire conversation history, including the plan, to a file. Alternatively, you can simply ask the agent to use the Write tool to save the roadmap into a markdown file once you switch back to default or acceptEdits mode.
What happens if I exit a session in the middle of a plan?
If you quit with Ctrl+C, your session history is preserved. You can return to it later by running claude --continue to pick up exactly where the planning discussion left off. Your position in the plan and the context window will remain intact.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.