Everything You Need to Know About Plan Mode in Gemini CLI

Home » Python » Everything You Need to Know About Plan Mode in Gemini CLI

Plan Mode in Gemini CLI is essentially a safe, read-only cockpit where you can think through complex changes before touching a single line of code. Instead of jumping straight into edits, you and the agent walk through research, design, and planning together, with Gemini combing through your codebase, your tools, and your documentation while keeping your project protected from accidental modifications.

This mode is designed for developers who want structure, safety, and clarity before implementation starts, without sacrificing speed or flexibility. You can use it to map out database migrations, new features, refactors, or audits, all while leveraging high‑reasoning models, custom policies, Agent Skills, and even headless workflows in CI/CD. Think of it as a planning sandbox where everything is deliberate and traceable.

What is Plan Mode in Gemini CLI?

Plan Mode is a read-only operating mode in Gemini CLI that limits the agent to a restricted set of safe tools. While it is active, Gemini can explore your repository, inspect files, search for patterns, and read documentation, but it cannot change your project files or run arbitrary commands that could alter state. The only files it is allowed to write are its own internal plan artifacts.

The main idea behind Plan Mode is to separate thinking from doing. First, Gemini focuses on understanding your request, analyzing the codebase, dependencies, and environment, and drafting a detailed plan. Only after you explicitly approve that plan does the CLI move into an editing or execution-capable mode to perform the changes.

Plan Mode is enabled by default for new users of Gemini CLI, which means most workflows already start in a research‑first mindset. You can always turn it off or remove it from your workflow, but the default behavior is to treat planning as a first‑class phase, especially for large or risky changes.

The mode is also tightly integrated with other Gemini features such as Agent Skills, the policy engine, MCP tools, and model steering. This makes it not just a safety mechanism but also a powerful environment for architecting robust, well‑reasoned solutions.

How to enable and enter Plan Mode

Plan Mode is usually turned on out of the box, but you can control how and when Gemini CLI starts in this mode. There are several ways to configure or enter Plan Mode depending on whether you want it as your default behavior or just for specific sessions.

If you want Gemini CLI to always start in Plan Mode, you can tweak your settings from inside the CLI. Run the /settings command, locate the option called “Default Approval Mode”, and set it to Plan. From that point forward, every new session will begin in this read‑only planning environment.

For one‑off sessions where you want to launch directly into Plan Mode, you can use a command-line flag. Start the CLI with gemini –approval-mode=plan and the agent will immediately operate under Plan Mode’s restrictions without you having to toggle anything interactively.

When you are already inside Gemini CLI, there are multiple ways to switch over to Plan Mode on the fly. You can press Shift+Tab to cycle through the available approval modes (Default → Auto‑Edit → Plan), use the /plan command, or simply ask in natural language for the agent to “start a plan for…” a given goal. Behind the scenes, Gemini invokes the enter_plan_mode tool to change modes.

The /plan command also lets you provide a goal inline, which is handy when you want to both switch modes and immediately start planning. For example, typing /plan implement authentication puts Gemini into Plan Mode and instantly submits your request about authentication design, kicking off research and analysis right away.

Core workflow: research, design, draft, approve

Plan Mode structures your work into a simple but powerful flow: define the goal, research, design, draft a plan, then approve or iterate. Each phase is intentionally separated so you can keep control and avoid unexpected edits or risky actions.

First, you provide a clear objective. You might say “plan a new notification service using Redis” or “research how to migrate this database.” Gemini uses that goal to enter Plan Mode (if not already active) and begins exploring the relevant parts of your codebase, infrastructure, and documentation in a strictly read‑only way.

During the research phase, Gemini uses tools like file listing, globbing, grep‑style search, and other read‑only capabilities to build a mental map of your system. In some cases, it may rely on specialized sub‑agents such as a codebase_investigator or activate Agent Skills tailored to specific domains to better understand dependencies and architecture.

Once the agent has enough context, it moves into the design and discussion phase. Here, Gemini proposes strategies, surfaces trade‑offs, and may ask you clarifying questions using the ask_user tool. This back‑and‑forth helps make sure the chosen approach aligns with your preferences, constraints, and existing conventions.

After you verbally agree on a direction, Gemini drafts a formal implementation plan as a Markdown file stored in your dedicated plans directory. This artifact is detailed and structured: it enumerates tasks, steps, dependencies, potential risks, and sometimes alternative options. You can read, edit, or annotate it before anything is executed.

The final step in the flow is explicit approval. Gemini CLI will present the plan and offer options such as “Yes, automatically accept edits” or “Yes, manually accept edits” to start implementation. If something feels off, you can push back with feedback, edit the plan file yourself, or simply cancel the plan with Esc and try a different approach.

Collaborating on the plan: discussion, edits, and comments

One of the standout advantages of Plan Mode is that it treats the plan as a shared artifact you and Gemini can co‑edit. This collaboration can be more precise and faster than describing complex changes purely in natural language prompts.

When Gemini finishes a draft and presents the plan for review, you can open it directly in your preferred external editor. Press Ctrl+X from inside the CLI and the Markdown plan will open in VS Code, Vim, or whatever editor you’ve configured. No manual file hunting required.

Inside the editor, you can modify the plan however you like. You might reorder steps to better fit your deployment pipeline, rewrite certain actions for clarity, remove tasks you consider unnecessary, or expand sections that need more detail. You can also add inline comments such as “Should we reuse the existing Logger class here?” or “Verify this against the current SLOs.”

Once you save and close the editor, Gemini CLI automatically detects your changes and comments. It parses the updated document, incorporates your feedback, and refines its internal understanding of the strategy. The agent then regenerates a polished version of the plan for you to review again.

This loop of edit → refine → review can repeat as many times as needed until you are satisfied with the plan. When you’re ready, you give a clear approval, and only then does Gemini move out of Plan Mode to begin actual edits or command execution based on the agreed‑upon steps.

Exiting Plan Mode and switching approval modes

You can exit Plan Mode at any time, whether you’re done planning or simply want to switch back to another approval mode. There is no requirement to finalize or approve a plan before leaving this environment.

The most common way Plan Mode ends is when you approve a finalized plan. As soon as you confirm that Gemini should start the implementation, the CLI automatically exits Plan Mode and transitions into a more permissive mode where edits and tool calls that change state are allowed, according to your approval settings.

If you just want to switch to another mode without approving anything, you can use the same keyboard shortcut used to enter Plan Mode. Press Shift+Tab to cycle from Plan back to Default or Auto‑Edit, depending on what you prefer for active development work.

Natural language commands also work for mode transitions. You can type phrases like “exit plan mode” or “stop planning” and Gemini will call the corresponding mode‑switching tool to restore your previous behavior. This makes it easy to jump in and out of the planning context as your workflow evolves.

Safety model and allowed tools in Plan Mode

Under the hood, Plan Mode is enforced by strict safety policies that guarantee your project stays in a read‑only state during planning. The mode is backed by the Gemini CLI policy engine and a dedicated configuration file named plan.toml, which defines which tools are permitted and how they behave.

The built-in policy for Plan Mode is considered a Tier 1 policy and is always focused on preventing writes or destructive actions. Only tools that are inherently safe—like file reading, searching, or listing—are allowed by default. Anything that could mutate files, run commands, or alter external systems is blocked unless you explicitly override the rules.

The policy engine treats rules that do not specify modes as globally active, meaning they will also apply during Plan Mode. If you want a rule to apply only in other modes and not in Plan Mode, you must explicitly list the target modes in that rule. For example, if you want npm test to be allowed in Default and Auto‑Edit modes but never in Plan Mode, you would configure it with a modes list that excludes Plan.

Another important safety feature is the way persistent tool approvals are scoped. Approvals granted in more permissive modes (like Default or Auto‑Edit) do not automatically carry over into Plan Mode. This prevents tools that you trust for implementation from silently running while you are still in the research phase. Approvals given during Plan Mode, however, are treated as deliberate and can be applied globally to other modes afterward.

Overall, Plan Mode is secure by default but still highly customizable. You can tailor which tools are available, how they require approval, and what kind of hooks or logging you want around plan creation and execution transitions.

Custom policies, MCP tools, and hooks

Beyond the built‑in Tier 1 policies, you can further adapt Plan Mode to your organization or personal workflow by adding your own policy files. These live in the ~/.gemini/policies/ directory and are considered Tier 2, so they can refine or extend the default behavior defined in plan.toml.

One common use case is controlling how read‑only Model Context Protocol (MCP) tools behave during Plan Mode. By default, Gemini may require user confirmation before invoking these tools, even when they are non‑destructive. With toolAnnotations and the mcpName wildcard, you can define specific patterns or tool sets that are auto‑approved or require fewer prompts, making planning smoother in environments that rely heavily on external services.

You can also attach hooks that trigger when Plan Mode transitions into implementation. For example, if your organization needs an audit trail of every approved plan, you can add an AfterTool hook that copies the finalized plan artifacts to Google Cloud Storage or another archive system whenever Gemini exits Plan Mode to start executing changes.

A typical hook might be a script such as ~/.gemini/hooks/archive-plan.sh, which receives context about the session and plan file. This lets you enforce compliance and traceability requirements without changing your manual workflow—every time a plan is approved, it’s automatically backed up for later review or incident analysis.

By combining custom policies and hooks, teams can encode their own methodologies directly into Plan Mode. Whether you want stricter approvals, mandatory logging, or environment‑specific tool restrictions, the policy engine gives you the knobs you need.

Agent Skills and specialized planning workflows

Agent Skills are a key mechanism for tailoring how Gemini CLI plans specific categories of work while staying inside Plan Mode. A skill packages specialized instructions, procedural steps, and heuristics that guide how the agent researches, designs, and structures a particular task.

For instance, a “Database Migration” skill might enforce that every plan includes backup strategies, data validation checks, and rollback procedures. Instead of remembering all of these details every time, you can rely on the skill to make sure each migration plan is safe and consistent with your standards.

Similarly, a “Security Audit” skill could push Gemini to actively look for vulnerabilities or misconfigurations during codebase exploration. It might instruct the agent to scan for insecure defaults, missing authentication checks, or unencrypted secrets, and then summarize findings and remediation steps inside the plan artifact.

On the front-end side, a “Frontend Design” skill can steer the agent toward specific UI component libraries and accessibility guidelines. Plans generated under this skill would automatically reference your design system, ARIA practices, or performance constraints, helping keep the UI consistent and inclusive.

To use a skill in Plan Mode, you can explicitly ask Gemini CLI to “use the <skill-name> skill to plan…” or simply describe your task in a way that allows the agent to activate a relevant skill autonomously. Once active, the skill reshapes how the planning phases behave, from research priorities to the structure of the final Markdown plan.

Because skills integrate smoothly with Plan Mode’s safety model, even highly specialized workflows still benefit from the read‑only guarantees and approval gates. You get deep, domain‑aware planning without exposing your environment to unintended side effects.

Model routing: Pro for planning, Flash for execution

Gemini CLI includes automatic model routing that takes advantage of Plan Mode to balance reasoning quality and execution speed. When you use an auto model configuration, the CLI chooses different Gemini models depending on whether you are in the planning or implementation phase.

While you’re in Plan Mode, requests are routed to a high‑reasoning Pro model, such as Gemini 3.1 Pro. This model is optimized for complex analysis, architectural decisions, long‑context reasoning, and drafting intricate plans. The goal is to maximize the quality and robustness of the plan itself, even if that requires more computation.

Once a plan is approved and you exit Plan Mode, the CLI detects that an implementation phase has started and automatically switches to a high‑speed Flash model. Here, the priority is responsiveness and cost efficiency: the agent is mostly executing well‑defined steps instead of making big strategic decisions, so a faster model is usually sufficient.

This default behavior provides a smart trade‑off: slow and thoughtful when designing, fast and efficient when building. If for any reason you prefer a different setup, you can disable automatic switching in your settings and configure specific models for each mode manually.

Newer models like Gemini 2.5 Flash and Gemini 2.5 Flash‑Lite continue to improve this balance. With better tool‑use capabilities, lower latency, and improved instruction following, they can execute plan steps more reliably while keeping token usage and costs in check.

Session retention, cleanup, and custom plan directories

To keep your development environment tidy, Gemini CLI automatically manages session data and associated plan files. By default, each session—including its plans and task trackers—is retained for 30 days before being cleaned up.

You can change this retention period using the /settings command or by editing your settings.json configuration directly. Look for the “Session Retention” setting and adjust it according to your needs; for long‑running projects you may want a longer window, while for ephemeral experiments you might prefer shorter retention.

In addition to automatic cleanup, you can trigger manual deletion of sessions at any time. From the command line, use gemini –delete-session <index|id> to remove a specific session and its artifacts. Alternatively, open the Session Browser with /resume, navigate using the interface, and press x to delete the selected session.

If you have configured a custom plans directory, it is important to note that automatic deletion does not remove those plan files. You are responsible for managing that directory manually, which can be an advantage if you want to treat plans as permanent documentation or store them in version control alongside your code.

This approach gives you flexibility: use short‑lived plans when you only care about immediate execution, or maintain a curated archive of strategic plans for future reference and compliance.

Non-interactive and CI/CD workflows with Plan Mode

Plan Mode is not just for interactive terminal sessions; it also plays nicely with non‑interactive environments like scripts and CI/CD pipelines. In these scenarios, the policy engine is configured to approve certain planning tools automatically so the workflow does not stall waiting for user input.

Specifically, when Gemini CLI detects a non‑interactive context, it automatically approves the enter_plan_mode and exit_plan_mode tools. This means your pipeline can programmatically trigger planning, let Gemini generate a plan, and then move into execution without manual confirmation dialogs.

Another key difference in non‑interactive workflows is what happens after Plan Mode finishes and implementation begins. Instead of transitioning to the standard Default mode, the CLI switches into YOLO mode, which is designed to execute steps automatically without getting stuck on interactive tool approvals.

This automation-friendly behavior makes it possible to build fully scripted workflows where planning and execution run end‑to‑end. You still benefit from the structured planning phase, but the pipeline can proceed at machine speed once the plan is ready and approved according to your policies.

Model steering inside Plan Mode

Model steering lets you nudge Gemini in real time while it’s researching or drafting a plan, which can significantly tighten the feedback loop and help mitigate model hallucinations. Instead of waiting for a full cycle to complete, you can interject hints or corrections while tools are running.

Imagine you start with a prompt like “/plan I want to implement a new notification service using Redis.” Gemini enters Plan Mode, starts scanning the codebase, and begins exploring directories. As you watch the tool calls—maybe it’s listing the wrong paths—you can type something like “Don’t forget to check packages/common/queues for the existing Redis config.”

Even while the spinner is active, Gemini can incorporate that hint into its current research. You’ll then see it inspect the suggested directory on the next turn and adjust its understanding of where the new service should live.

Model steering is just as useful during the drafting phase. If the initial plan leans toward a simple queue architecture but you prefer a Pub/Sub pattern, you can say “Let’s use a Publisher/Subscriber pattern instead of a simple queue for this service.” Gemini will pause, reconsider the design, and start drafting a new version of the plan aligned with your preference.

To get the most out of steering, try to be specific and intervene early. Clear instructions like “use the existing Logger class in src/utils” or “we plan to deprecate this module next month” provide context that may not be obvious from static code analysis alone.

Extensibility with Conductor and complex workflows

For large or multi-step projects, the Conductor extension showcases how Plan Mode can become the backbone of more advanced workflows. Conductor is designed for Context‑Driven Development, acting as an orchestrator that guides you through complex migrations, feature rollouts, or refactors.

By leveraging Plan Mode, Conductor can run comprehensive pre‑flight checks and deep research passes in a completely safe environment. It breaks large tasks into milestones, uses the ask_user tool to validate critical decisions at each stage, and ensures the agent never rushes into changes without your high‑level approval.

Throughout this process, Conductor relies on Plan Mode’s read‑only principles and structured planning to generate sub‑tasks and detailed steps. At each checkpoint, it confirms assumptions, gathers missing information, and updates the overall trajectory so the final implementation is both thorough and aligned with your strategy.

The design of Plan Mode with tools like enter_plan_mode and exit_plan_mode was deliberately made extensible so solutions like Conductor can build on top of it. The goal is not just to give you a safe planning toggle, but a foundation you can use for your own custom orchestration layers and development methodologies.

The Gemini CLI team is working on bringing Conductor closer to the core experience as a built‑in mode, further blurring the line between planning, orchestration, and execution. That direction highlights how central Plan Mode is to the future of structured, AI‑assisted development.

Overall, Plan Mode in Gemini CLI is more than a simple safety switch; it is a complete planning environment that blends read‑only exploration, rich collaboration, customizable policies, high‑reasoning models, and automation‑friendly behavior. By embracing this mode for your next big feature, migration, or audit, you give yourself a clear space to think, question, and iterate before any code changes land, which ultimately leads to cleaner implementations and fewer unpleasant surprises.