Claude Code Plan Mode vs Auto Mode: Choosing the Right Execution Strategy
Every Claude Code session starts with a choice, even if you never consciously make it. By default, Claude Code runs in auto mode: it reads your prompt, reasons through a plan internally, and starts executing. Files get written, tests run, commits happen. You see the results when it stops.
Plan mode changes that contract. With the --plan flag, Claude Code produces a written plan of proposed actions before a single file is touched. You review it, approve it, and then execution begins.
Neither mode is universally better. The right choice depends on the blast radius of the task and how well you understand the codebase.
The difference between plan mode and auto mode is the difference between reviewing a surgery plan and waking up after the operation. For high-stakes changes, you want to see the plan.
Auto Mode: How It Actually Works
Auto mode is Claude Code’s default. When you run claude without additional flags, you are in auto mode.
In auto mode, Claude Code executes a loop internally: it thinks through the task, identifies actions to take, executes them, observes the results, and iterates. This loop is not invisible to you. Claude Code logs each action it takes in the terminal output. But it does not stop to ask for approval between steps.
Auto mode is fast. A well-scoped task in a familiar codebase completes without interruption. For greenfield projects where mistakes are cheap and git commits create natural checkpoints, auto mode is the right default.
The risk in auto mode appears when the task is less scoped than it seemed. Claude Code may correctly interpret a vague instruction in a way that touches more files than you expected.
In an unfamiliar codebase, "refactor the authentication module" can cascade into changes you did not anticipate.
Auto mode trusts that the task description was precise enough to guide safe autonomous execution. That trust is warranted more often than not, but it needs to be earned by the specificity of the prompt and the familiarity of the codebase.
Plan Mode: What It Shows You
Plan mode is invoked with the --plan flag when starting a session:
claude --plan "refactor the user authentication module to use JWT tokens"You can also enter plan mode mid-session with the /plan command. Claude Code will produce a written plan before acting on subsequent instructions.
The plan output includes the files Claude Code intends to read, the files it intends to modify or create, the sequence of actions it will take, and any tests it plans to run. It does not execute anything until you approve.
What to check when reviewing a plan:
- Scope: are the listed files the ones you expected? Unexpected files in the plan warrant a prompt revision before proceeding.
- Sequence: does the order of operations make sense? A plan that modifies the database schema before updating the application layer is backwards.
- Tests: does the plan include running the test suite? If not, add that requirement to the prompt before approving.
- Reversibility: does the plan include git commits at logical checkpoints, or does it propose one large terminal action?
A plan that looks wrong is far cheaper to reject than an execution that went wrong.
How to Invoke Plan Mode
Two ways to use plan mode:
At session start:
claude --plan "migrate the orders table to add a status column and update all queries"Claude Code produces the plan, waits for your approval, then executes.
Mid-session with /plan:
If you are already in a Claude Code session and want to switch to plan-before-execute behavior for the next instruction:
/plan
refactor the payment processing module to use the new Stripe APIClaude Code will show the proposed plan before acting. This is useful when a session that started with low-risk tasks moves into higher-risk territory.
The hybrid approach is often the most practical: start in plan mode for the first task in an unfamiliar area, approve and execute, then continue in auto mode for subsequent scoped tasks in the same session once you have confirmed Claude Code’s understanding of the codebase.
Scenario Comparison
| Scenario | Plan Mode | Auto Mode | Why |
|---|---|---|---|
| New hire onboarding to unfamiliar codebase | Recommended | Risky | Need to verify Claude Code’s model of the codebase before changes |
| Database schema migration | Required | Not recommended | Irreversible actions warrant plan review |
| Auth code changes | Recommended | Risky | Security-sensitive, high blast radius |
| Writing tests for existing code | Optional | Fine | Read-heavy, low blast radius |
| Adding a new API endpoint to a known module | Optional | Fine | Scoped, reversible, familiar context |
| Greenfield project, first feature | Optional | Fine | Git commits are the safety net |
| Refactoring across multiple modules | Recommended | Risky | Cross-file scope is hard to predict |
| CI pipeline debugging | Optional | Fine | Primarily read and observe, low write risk |
Safe Patterns for Both Modes
For auto mode:
Keep prompts scoped to a single module or task boundary. Commit frequently with git commit instructions in the prompt. Use --allowedTools to restrict which tools Claude Code can use if you want an additional guardrail.
Review the terminal output as execution proceeds rather than waiting for completion.
For plan mode:
Do not approve a plan you have not fully read. If any part of the plan is unclear, reject it and revise the prompt to be more specific. Treat the plan as a contract: if execution deviates from the plan, stop and investigate. Use plan mode for any task touching production configuration, database schemas, authentication logic, or payment integrations.
The hybrid approach:
Start in plan mode. Once the plan is approved and execution begins, subsequent tasks in the same session can run in auto mode if they are scoped and the first plan confirmed Claude Code’s understanding. This preserves speed without sacrificing safety on the first, highest-uncertainty action.
Plan mode and auto mode are not competing philosophies. They are tools for different risk profiles. The skill is knowing which one the current task requires. The Claude Code course covers both modes and how to build safe, effective development workflows around them.
Frequently Asked Questions
What happens if I reject a plan in plan mode?
Nothing executes. You can revise your prompt and ask for a new plan, or end the session. Rejection has no side effects since no files have been modified. This is the core value of plan mode: the cost of a wrong plan is zero.
Can I switch from auto mode to plan mode mid-session?
Yes. Use the /plan command during any active session to switch to plan-before-execute behavior for subsequent instructions. The switch takes effect immediately.
You can also go back to auto mode behavior by simply issuing instructions without the /plan prefix after that.
Does plan mode slow down development significantly?
For tasks where you already understand the codebase and the scope is clear, plan mode adds two to five minutes per major task for the review step. For tasks where plan mode catches an unexpected scope problem, it saves hours. The overhead is low enough that defaulting to plan mode for any task touching production infrastructure is almost always worth it.
Should I always use plan mode for database migrations?
Yes. Database migrations are the canonical plan-mode use case: they are often irreversible, they affect production data, and the sequence of operations matters. Running a migration in auto mode without reviewing the proposed steps is the kind of decision that leads to a rollback incident. Use plan mode, review the migration script before it runs, and add a human checkpoint before the production apply step.
Ready to build safer Claude Code execution patterns for your team?
Start by defaulting to plan mode for any task touching production infrastructure, and add the /plan command to your session workflow for high-stakes changes until reviewing plans becomes second nature.
Path one: set it up yourself. Use the --plan flag and checkpoint patterns in this article to add the right human review steps to your workflow.
The Claude Code course covers how to combine plan mode with other execution controls for consistent, safe development.
Path two: work with Phos AI Labs. If you want to implement Claude Code with the right execution controls and human checkpoints built in from the start, including plan mode policies, permission scoping, and team rollout, we design and run that implementation. Phos AI Labs is a CCA-F certified Claude implementation partner. Thirty minutes, no deck. Start here.