Gemini CLI plan mode puts Google's terminal coding agent into a read-only state, lets it research your repository, and writes a Markdown plan you approve before any file changes. The point is a review gate, not a smarter prompt. Everything before approval is research, and implementation starts only after you approve the plan file.
Part 4 of a series. Start with What is Gemini CLI plan mode?, then How to use Gemini CLI plan mode safely.
What is Gemini CLI plan mode?
Gemini CLI plan mode is a read-only planning phase inside Google's terminal coding agent. During that phase the agent reads your repository, searches for relevant patterns, and writes an implementation plan as a Markdown file, while write tools are blocked so files cannot be changed before you approve the plan.
The mechanism is a policy restriction rather than a prompt instruction. The transcript, a developer walkthrough of the feature, describes write tools being blocked at the policy level, which is why the guarantee is presented as enforceable rather than aspirational. You can verify the current behavior against the Gemini CLI documentation rather than trusting a video summary.
Two things separate this from a chat message asking the model to think first. The plan exists as a file you can open, edit, and reorder, and implementation begins only after an explicit approval step.
Gemini CLI itself is Google's free, open-source AI tool that lives in your terminal. It installs with one command, npm install -g @google/gemini-cli, and gives you an agent that can read your files, write code, run commands, and search the web from the command line. Plan mode runs on top of that agent, and it shipped alongside a switch that made Gemini 3 the default model for everyone. There is a free tier: sign in with your Google account and you get up to 1,000 requests a day at no cost.
How the read-only planning phase works
The planning phase runs as a research loop: the agent maps the project structure, traces relevant code paths, and then either continues or asks you a clarifying question. A caching layer for an existing API, for example, might prompt a question about in-memory versus Redis storage, or whether the cache applies globally or per route.
The built-in codebase investigator sub-agent explores the workspace during this phase and surfaces context the planner would otherwise miss. Version 0.33, released March 11, 2026, expanded that sub-agent's capabilities during planning, according to the release notes. Treat the expansion as a documented change to the research step, not as proof that the planner now understands every repository.
Model routing is part of the design the transcript describes. Planning uses the higher-reasoning Pro model, and implementation switches to the faster Flash model once you approve the plan. That routing is the speaker's account of the feature, so confirm current model assignments in the documentation before relying on them.
Once the agent has enough context, it writes the plan step by step and file by file. You read it, push back on specific steps, or change the approach before approving.
Gemini CLI plan mode workflow, step by step
The workflow is short: activate plan mode, describe the task, answer any questions, review the plan file, edit it, approve it, and only then let implementation run. The order matters because approval is the single point where the agent gains permission to write.
- Install the CLI with
npm install -g @google/gemini-cliand sign in with your Google account. - Navigate into your project directory and start the CLI.
- Enter plan mode by typing
plan, pressing Shift+Tab, or describing the task in a way that triggers planning, such as asking it to start a plan for a feature. - Describe the feature in your own words and let the agent research the codebase.
- Answer any clarifying questions it asks before writing the plan.
- Open the generated Markdown plan, edit steps, reorder them, or leave comments.
- Approve the plan, which starts implementation.
The exact command names, shortcuts, and installation package are version-dependent. Confirm them in the current Gemini CLI repository before scripting anything around them.
What shipped in Gemini CLI 0.32 and 0.33
Version 0.33 shipped on March 11, 2026 with three plan-mode changes, and version 0.32 shipped on March 3, 2026 with external editor integration and better handling of complex tasks. The version numbers and dates come from the speaker's walkthrough and should be checked against the project's own release list before you cite them.
Per that walkthrough, 0.33 expanded the codebase investigator sub-agent during planning, added annotation support so feedback can be left inside the plan file for the agent to read and respond to, and added a command for copying an approved plan out of the tool. Version 0.32 added the external editor flow, which lets you open the plan in your own editor, rewrite steps, and have the CLI pick up those changes.
Plan mode has been the focus of recent releases, with updates arriving roughly every couple of weeks. That cadence is the reason to read the changelog rather than a months-old article about the feature.
What plan mode does and does not fix
Plan mode addresses premature action, not incorrect reasoning. An agent that misreads a dependency can still write a confident plan around that misreading, and approving the plan locks in the mistake you failed to catch. The review step is the control; it is not an automatic correctness check.
The review gate is the part worth understanding. In the without-plan-mode case the agent starts coding immediately and a wrong assumption surfaces ten minutes later or in production. With plan mode the assumption is written down before execution, which means the cost of catching it drops from a debugging session to a paragraph edit.
The failure modes without the gate are specific and familiar to anyone who has used AI coding tools: the agent overwrites the wrong file, or builds the right thing in the wrong place, and you notice ten minutes later or not until production breaks. The problem is not that the model writes bad code. It skips the thinking step a senior engineer would never skip: read the existing code, work out the approach, ask a few questions, then start.
Scope is also worth keeping straight. Plan mode governs what the agent may do before approval, so it does not by itself guarantee safe execution afterward, isolate you from a compromised dependency, or make the agent suitable for regulated workloads. Local execution and an approval gate support a controlled workflow; they do not constitute compliance evidence.
| Aspect | Without plan mode | With plan mode |
|---|---|---|
| First action | Edits files | Reads the codebase |
| Output before approval | Code changes | A Markdown plan |
| Write access during planning | Available | Blocked by policy |
| Cost of a wrong assumption | Debugging later | A paragraph edit |
| Model used | Execution model | Reasoning model, then execution model |
Where plan mode fits for teams and legacy code
Teams get the most from plan mode on work where a wrong assumption is expensive: shared repositories, legacy code, and features that touch many files. The plan file is a reviewable artifact, which means a change to a two-year-old service can be discussed before it is written rather than after it is merged.
The transcript also describes enterprise policy configuration in Gemini CLI, where administrators can restrict which tools are allowed and enforce specific authentication. That is a configuration surface, not a compliance certification, and the controls an organization actually needs depend on its own requirements.
The broader argument is about trust, and it holds in a narrow form. Seeing the intended change before it happens is what makes an agent usable on work that matters. Plan mode makes that visible; it does not make the agent right. Reviewers still carry that responsibility.
Is Gemini CLI plan mode a replacement for code review?
No. Plan mode is a pre-implementation gate, while code review happens after code exists, and the two catch different classes of problem. A plan can be sound while the resulting diff is sloppy, and a diff can be fine while the plan chose the wrong approach.
The practical division is straightforward. Use plan mode to agree on approach, files, and sequencing before anyone writes code. Use review and tests to check the implementation that follows. Neither substitutes for the other, and a plan approved in a hurry offers the same false comfort as a diff approved in a hurry.
The skill that plan mode rewards is reading a plan critically: checking whether the files listed are the right ones, whether the dependencies named actually exist, and whether the sequencing avoids a half-migrated state. That skill is what the feature shifts attention toward.
FAQ
- Does Gemini CLI plan mode change files before approval? No. During planning, write tools are blocked at the policy level, so the agent can read files, search the codebase, and write a plan document without modifying project files. Implementation begins only after you approve the plan. Confirm the current enforcement behavior in the official documentation for your installed version.
- Which model does Gemini CLI use in plan mode? The video walkthrough states that planning uses a higher-reasoning Pro model and implementation switches to a faster Flash model after approval. Model names and routing change frequently, so check the provider's current model documentation rather than relying on a video description.
- Can I edit the plan before approving it? Yes. The plan is a Markdown file. You can edit steps directly, reorder them, leave comments, or open it in your own editor, and the CLI picks up those changes. Version 0.32 added the external editor integration and version 0.33 added annotation support, per the walkthrough.
- Is plan mode available on the free tier? The transcript describes a free tier with Google account sign-in and a daily request allowance of up to 1,000 requests. Free-tier limits and request quotas are volatile, so verify the current allowance on the official pricing or documentation page before planning around it.
- Does plan mode make AI coding safe for production repositories? It reduces one class of risk by making the agent's intent reviewable before execution. It does not validate the plan itself, guarantee correct code, or provide compliance guarantees for regulated environments. Those depend on your review process and your organization's controls.
Turning a walkthrough into something you can reread
Julian, the creator of the walkthrough summarized here, opens his videos by saying he makes them to help people learn and implement AI tools. Gustavo dev doido, a developer known on YouTube for Portuguese-language programming content, is another example of the kind of teaching that lands better in writing than in a video timeline. Walkthroughs like this one carry a sequence: activate, research, review, approve. That sequence is easy to lose when it only exists as speech.
The same gap applies to anyone with a YouTube library. A video can explain a workflow clearly and still be hard to search, cite, or hand to a colleague six months later.
If you have explanations, interviews, or lessons sitting in video form, that content can become something people find and read. Paste a YouTube URL into Skala Blog, let it transcribe the video, and you get a structured article draft you can edit before publishing.
Fork this article
Start a new branch from the same video, shaped your way. You keep the credit; the original keeps the attribution.
A fork in another language is filed as a translation of this article, so the two pages point at each other. You can unlink it later from the editor.
0/240
You are creating
- Format
- For
- Language
- Source
- Your angle
You will be asked to sign in before it is generated.
Buy credits