Gemini CLI Plan Mode for Production Repos

The Verdict

Use Gemini CLI Plan Mode when you want an agent to research a production repository without granting write access yet. Do not treat it as the whole safety system. It is the first gate in a repo workflow that still needs ownership, context files, sandboxing, CI, and a human approval before edits.

The feature itself is useful: Plan Mode is a read-only environment for researching, designing, and planning before implementation, and Google's current docs say it is enabled by default. The production value is the pause it creates. The agent can inspect files, search the repo, read approved context, ask questions, and draft an implementation plan before touching application code.

That pause matters more than the model brand. For the broader terminal-agent choice, the useful comparison is still Codex vs Claude Code vs Gemini CLI for production teams. Plan Mode answers a narrower question: how do you stop the first agent action from becoming an unreviewed patch?

The answer is to make planning a required state for high-blast-radius work:

• schema migrations
• auth and permission changes
• billing, quota, or entitlements work
• large refactors across packages
• security-sensitive dependency upgrades
• any task where the agent needs external context before editing

Small fixes can still go through a normal edit flow. Production repo work should start in Plan Mode when the cost of a wrong assumption is higher than the cost of one planning turn.

What Changed After June 18

Validate the access path before standardizing on Gemini CLI, because Google changed the consumer story on June 18, 2026. Google's transition note says Antigravity CLI became available to everyone, and that Gemini CLI plus Gemini Code Assist IDE extensions stopped serving requests for Google AI Pro, Ultra, and free Gemini Code Assist for individuals on June 18, 2026.

That does not mean every Gemini CLI production rollout is dead. The same Google note says organizations using Gemini CLI or IDE extensions through Gemini Code Assist Standard or Enterprise, or Gemini Code Assist for GitHub through Google Cloud, have unchanged access. It also says Gemini CLI remains accessible through paid Gemini and Gemini Enterprise Agent Platform API keys.

The practical rule:

The quota page is still useful, but it is not the rollout decision by itself. It lists account-type limits such as 1,000 maximum model requests per user per day for Gemini Code Assist Individual, 1,500 for Google AI Pro, 2,000 for Google AI Ultra, 1,500 for Gemini Code Assist Standard, and 2,000 for Gemini Code Assist Enterprise. After the June 18 consumer cutover, a team should read those numbers with the transition note beside them and confirm the actual supported auth route before putting the workflow into engineering policy.

The Production Rollout Pattern

The right rollout is plan, review, then edit under a separate approval mode. Plan Mode can start with gemini --approval-mode=plan, through /settings by setting Default Approval Mode to Plan, with Shift+Tab, with /plan [goal], or by asking Gemini CLI to start a plan. For team work, prefer the explicit launch or default setting so the first run is predictable.

The important distinction is that approval is not a vibe check. A production plan should have the same shape as a lightweight design review:

## Goal
Move billing webhook signature verification from per-route helpers to shared middleware.

## Allowed files
- apps/api/src/webhooks/*
- packages/billing/src/signatures.ts
- packages/billing/test/signatures.test.ts

## Non-goals
- No billing provider migration
- No entitlement schema changes
- No production secret changes

## Required checks
- pnpm test packages/billing
- pnpm test apps/api -- webhooks
- pnpm lint

## Human approval
- API owner reviews middleware behavior
- Platform owner confirms no secret rotation is needed

That plan format is intentionally plain. It gives the agent a local contract and gives the reviewer something concrete to reject.

The closest parallel in the existing DVNC.dev coverage is Claude Code planning mode for production teams. The implementation details differ, but the policy is the same: planning mode is useful when it produces reviewable intent before any write-capable run.

The Settings That Matter

Production teams should configure Plan Mode as a repo policy, not a personal habit. The defaults help, but team reliability comes from making the mode, plan location, model routing, sandbox, and context files explicit.

Start with approval mode:

{
  "general": {
    "defaultApprovalMode": "plan",
    "plan": {
      "enabled": true,
      "modelRouting": true
    }
  }
}

Google's configuration docs say general.defaultApprovalMode supports default, auto_edit, and plan; YOLO mode is command-line only. They also say general.plan.enabled defaults to true, and general.plan.modelRouting defaults to true, using Pro for planning and Flash for implementation. Keep model routing on unless you have a measured reason to disable it. Planning is where you want the stronger reasoning path.

Next, decide where plans live. By default, Gemini CLI stores planning artifacts outside the project at ~/.gemini/tmp/<project>/<session-id>/plans/. That is safer than letting arbitrary writes happen inside the repo, but it is weaker for team review because the plan can disappear from the normal code review trail.

For teams, a project-local plan directory can be useful:

{
  "general": {
    "plan": {
      "directory": ".gemini/plans"
    }
  }
}

Use that only with a matching policy that allows writes to Markdown plan files in that directory. The docs are clear that custom directories require policy updates. That friction is healthy: the only files Plan Mode should write are plan files.

Then configure repository context. Gemini CLI context files default to GEMINI.md, and the file name is configurable through context.fileName. Put the durable team rules there:

# GEMINI.md

## Planning rules
- Start risky changes in Plan Mode.
- Plans must list allowed files, non-goals, required tests, and rollback.
- Never propose changing secrets, CI permissions, or production config without owner approval.
- Prefer existing repo helpers over new framework choices.

## Test commands
- pnpm lint
- pnpm test
- pnpm typecheck

## Review rules
- Any auth, billing, database, or infra change needs owner review before implementation.

Finally, turn on sandboxing when the agent moves from planning to execution. Gemini CLI can enable sandboxing with -s or --sandbox, with GEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc, or with {"tools": {"sandbox": true}} in settings. On macOS, Seatbelt profiles can restrict writes outside the project. With Docker or Podman, the current working directory is mounted at the same absolute path inside the container, which keeps project-relative behavior stable while isolating execution.

Plan Mode is read-only by policy. Sandbox is for the next phase, when writes and commands become possible.

What Breaks First

The first failure is stale access assumptions. A team reads an old Gemini CLI quota table, tells engineers to use personal accounts, and discovers the workflow is now supposed to move through Antigravity CLI. The fix is boring and necessary: write the supported account path into the rollout doc, then verify it with a real login before training the team.

The second failure is read-only MCP sprawl. Plan Mode allows read-only MCP tools, and the launch blog highlights that it can read context from developer stack systems such as GitHub issues, Postgres schemas, or docs. That is useful only if the tools are actually read-only and scoped. A "read schema" tool is different from a "run arbitrary SQL" tool with a polite prompt. Use tool annotations and policies to auto-approve only read-only MCP tools in Plan Mode. Keep everything else behind confirmation.

The third failure is hidden write paths. Plan Mode lets write_file and replace write Markdown plan files in the allowed plan directory. That exception is correct, but it should stay narrow. If you configure .gemini/plans, create a policy that only permits Markdown plan writes there. Do not add broad shell permissions to Plan Mode because a specific task was inconvenient once.

The fourth failure is plan approval without CI reality. A plan that does not name tests is not ready. Make Gemini CLI include the exact commands. Then keep the implementation phase behind the repo's normal branch protection. The plan should not bypass CI, code owners, secret scanning, dependency review, or required approvals.

The fifth failure is cost and quota blindness. Gemini CLI's quota docs list daily request limits by account type and recommend /stats model to inspect current session token usage and applicable limits. Use that command during pilots. Long planning sessions over large repositories can still burn quota, especially if the plan loops through broad context repeatedly.

The check we use for repo-agent pilots is simple:

The Decision Rule

Use Gemini CLI Plan Mode for production repositories only when your team has a supported Gemini CLI access path and can enforce planning as policy. If the team is on consumer Google AI Pro, Ultra, or free Gemini Code Assist for individuals after June 18, 2026, move the terminal rollout decision to Antigravity CLI instead of pretending Gemini CLI policy has not changed.

If Gemini CLI is still the right tool, the rollout rule is:

1. Default risky work to Plan Mode.
2. Keep write-capable modes separate from planning.
3. Store plans where reviewers can inspect them.
4. Scope read-only MCP access with policy.
5. Run implementation only after tests, owners, and rollback are named.

That is the line between a useful coding agent and an unreviewed patch generator. Plan Mode gives the repository a pause. Your engineering system has to decide what happens during that pause.