Gemini CLI Plan Mode

Plan Mode lets you preview, review, and approve a structured execution plan before Gemini CLI modifies any files. It is the safest and most powerful way to handle complex refactoring, migrations, and multi-file changes.

What is Plan Mode?

Plan Mode is a deliberate execution strategy built into Gemini CLI that separates planning from execution. Instead of immediately modifying your files when you issue a prompt, Gemini CLI first generates a detailed, step-by-step plan that describes every change it intends to make. You can then review each step, approve or reject individual changes, edit the plan, and only execute when you are fully satisfied.

This approach is ideal for tasks that touch multiple files or involve significant architectural changes. When you refactor an authentication module, migrate a database schema, or restructure an entire directory, you want to understand the full scope of changes before any file is modified. Plan Mode gives you that visibility and control.

Think of Plan Mode as a "dry run" with the ability to fine-tune. Gemini CLI uses its full understanding of your codebase to propose a plan, and you act as the final reviewer before anything is committed. This dramatically reduces the risk of unintended side effects and makes it easier to work confidently on large-scale changes.

How to Enter Plan Mode

There are several ways to activate Plan Mode depending on your workflow. You can invoke it directly from the command line, switch to it during an interactive session, or generate a plan without executing it at all.

Direct Command

Use the plan subcommand followed by your task description. Gemini CLI will analyze your codebase and generate a plan immediately.

gemini plan "Refactor the auth module to use OAuth 2.0"

Interactive Mode

If you are already in an interactive Gemini CLI session, type /plan to switch into Plan Mode. Your next prompt will generate a plan instead of executing changes directly.

> /plan

Switched to Plan Mode. Your next prompt will generate a plan.

> Migrate all API routes from Express to Fastify

Plan-Only Flag

Use --plan-only to generate and display a plan without any option to execute. This is useful for estimation, code review preparation, or sharing the plan with your team before proceeding.

gemini plan --plan-only "Convert the monolith to microservices"

Plan Mode vs Normal Mode

Understanding when to use Plan Mode versus Normal Mode helps you choose the right approach for each task. Here is a side-by-side comparison.

Normal Mode

  • • Immediate execution of changes
  • • Best for simple, single-file tasks
  • • Changes applied directly to files
  • • Quick feedback loop
  • • No pre-approval step required
  • • Ideal for generating code snippets or quick edits

Plan Mode

  • • Plan first, then review, then execute
  • • Best for complex, multi-file changes
  • • You can edit the plan before running it
  • • Full visibility into every proposed change
  • • Approval required before execution
  • • Ideal for refactoring, migrations, and architecture changes

When to Use Plan Mode

As a rule of thumb, use Plan Mode whenever a task involves more than two files, requires changes to shared interfaces or APIs, or could have cascading effects across your codebase. If you are unsure, start with Plan Mode. You can always approve and execute quickly, but you cannot undo changes that were applied in Normal Mode without reverting through version control.

Step-by-Step Example

Let us walk through a real-world scenario: refactoring an Express.js application from callback-based route handlers to modern async/await patterns. This is a multi-file change that benefits greatly from Plan Mode.

Step 1: Enter Plan Mode

Start by describing the task clearly. The more specific your prompt, the better the generated plan will be.

gemini plan "Refactor all Express route handlers in src/routes/ from callbacks to async/await. Update error handling to use try/catch blocks and ensure all middleware is compatible."

Step 2: Review the Plan

Gemini CLI analyzes your codebase and presents a structured plan. Each step lists the target file, the type of change, and a description of what will be modified.

Plan: Refactor Express routes to async/await

───────────────────────────────────────────

Step 1: src/routes/users.js

- Convert getUserById callback to async/await

- Wrap handler body in try/catch

- Replace next(err) with catch block

 

Step 2: src/routes/auth.js

- Convert login and register handlers to async/await

- Update bcrypt.compare to use await

- Add try/catch error handling

 

Step 3: src/routes/products.js

- Convert CRUD handlers to async/await

- Update database queries to use await

 

Step 4: src/middleware/errorHandler.js

- Update error handler to work with async errors

- Add asyncWrapper utility function

 

4 files affected | Estimated: ~120 lines changed

Step 3: Approve or Edit

You have full control. Approve the entire plan, edit individual steps, or add new steps. In this example, we add a step to update the test files as well.

> approve steps 1-4

> add step "Update test files in tests/routes/ to use async assertions"

Plan updated. 5 steps ready for execution.

> execute

Step 4: Execute and Verify

Gemini CLI executes each step sequentially, showing progress as it goes. After completion, run your test suite to verify the changes work correctly.

Executing plan...

[1/5] Updating src/routes/users.js ........... done

[2/5] Updating src/routes/auth.js ............ done

[3/5] Updating src/routes/products.js ........ done

[4/5] Updating src/middleware/errorHandler.js . done

[5/5] Updating tests/routes/ ................. done

 

Plan executed successfully. 5/5 steps completed.

Run your test suite to verify: npm test

Advanced Plan Mode Usage

Beyond basic plan-and-execute workflows, Plan Mode offers several advanced features for teams and complex projects. These capabilities let you save, share, resume, and customize plans for maximum flexibility.

Save Plans to a File

Export a plan to a markdown file for documentation, code review, or team discussion. The saved file contains every step, the affected files, and the rationale for each change.

gemini plan --save migration-plan.md "Migrate from MySQL to PostgreSQL"

Resume a Saved Plan

Load a previously saved plan and continue where you left off. This is useful for long-running migrations or when you want to execute a plan across multiple sessions.

gemini plan --resume migration-plan.md

Partial Execution

You do not have to execute every step in a plan. Approve only the steps you want to run, skip steps that need manual attention, and come back to them later.

> approve steps 1,2,4

> skip step 3

> execute

Executing 3 of 4 steps... Step 3 skipped.

Plan Templates

Create reusable plan templates for common operations. Define the steps once, then apply them to different projects or modules with a single command.

# Create a template

gemini plan --save-template add-feature-template.md "Standard feature workflow"

 

# Use a template

gemini plan --template add-feature-template.md "Add user profile page"

Common Plan Mode Patterns

Experienced developers tend to use Plan Mode in recurring patterns. Here are three proven workflows that work well for different types of tasks.

Bug Fix Plan

A disciplined four-step approach to fixing bugs: identify the root cause, write a failing test, implement the fix, and verify the test passes. This ensures the bug does not regress.

gemini plan "Fix the race condition in the WebSocket message handler"

 

# Generated plan:

Step 1: Identify - Trace the race condition in src/ws/handler.js

Step 2: Test - Write failing test in tests/ws/handler.test.js

Step 3: Fix - Add mutex lock to message processing pipeline

Step 4: Verify - Run test suite and confirm the fix

Feature Plan

A comprehensive workflow for building new features end-to-end: design the interface, implement the logic, write tests, and generate documentation.

gemini plan "Add rate limiting middleware to the API"

 

# Generated plan:

Step 1: Design - Create RateLimiter class interface in src/middleware/

Step 2: Implement - Build sliding window rate limiter with Redis backend

Step 3: Test - Add unit and integration tests

Step 4: Document - Update API docs and README with rate limit info

Migration Plan

A systematic approach to codebase migrations: audit the current state, transform the code, validate the results, and clean up deprecated artifacts.

gemini plan "Migrate from CommonJS to ES Modules"

 

# Generated plan:

Step 1: Audit - Scan all files for require() and module.exports usage

Step 2: Transform - Convert require() to import, module.exports to export

Step 3: Validate - Update package.json type field, fix import paths

Step 4: Cleanup - Remove .cjs fallbacks, update build config

Troubleshooting Plan Mode

Plan Mode is designed to be robust, but you may occasionally encounter issues. Here are the most common problems and their solutions.

Plan is Too Vague

If the generated plan lacks detail or specificity, the issue is almost always the prompt. Provide more context about your codebase, the specific files involved, and the exact outcome you want.

# Too vague:

gemini plan "Fix the API"

 

# Much better:

gemini plan "Fix the 500 error in POST /api/users when the email field contains unicode characters. The validation in src/validators/user.js needs to handle UTF-8 input."

Plan Does Not Match Your Architecture

If the plan suggests changes that do not align with your project structure or coding conventions, use a GEMINI.md file in your project root to provide governance rules. This file tells Gemini CLI about your architecture decisions, coding standards, and constraints. For example, you can specify that all database queries must go through the repository layer, or that all new files should follow a specific naming convention. Gemini CLI will respect these rules when generating plans.

Execution Fails Mid-Plan

If the plan fails during execution, Gemini CLI automatically creates a checkpoint so you can resume from where it stopped. Use the --resume flag to pick up from the last successful step.

Error at step 3/5: Could not resolve import path

Checkpoint saved. Resume with:

gemini plan --resume

 

# Fix the issue manually, then resume:

gemini plan --resume --from-step 3

Related Questions

Subagents: Parallel Task Delegation

Learn how Gemini CLI delegates tasks to subagents for parallel execution

Run Your First Command

Get started with Gemini CLI basics and your first prompt

Automate Tasks with Gemini CLI

Set up automation scripts, CI/CD integration, and scheduled tasks

Code Editing with Gemini CLI

Edit, refactor, and improve code using AI-powered suggestions

Master Plan Mode

Start using Plan Mode for your next complex task and experience the difference that structured planning makes:

Automation GuideCode EditingCustom Tools