Skip to main content

Buyer guide

Gemini CLI Workflow Playbook

GEMINI.md context, approval modes, checkpoints, and review practice for engineers running Gemini CLI on Code Assist, Vertex AI, or a paid API key.

Reading time
3 min read
Sources
11 cited
In this piece
Gemini CLI−3 Mixed

Put repository context in GEMINI.md, match the approval mode to the task, keep checkpointing on, and require a passing test before any agent change merges. Since June 18, 2026, Gemini CLI needs an existing Code Assist Standard or Enterprise subscription, a paid API key, or Vertex AI. Google stopped selling new Code Assist subscriptions on October 9, 2026.

When you need this

  • Engineers on your Code Assist licenses get different results from the same agent on the same repository.
  • Agent sessions return diffs too large for a reviewer to read in one sitting.
  • Engineers repeat the same conventions in every prompt because the repository does not hold them.
  • Sessions loop on a failing test or stop to ask engineers to run commands themselves.

Evaluation criteria

  1. Write GEMINI.md context

    What does the agent need to know before it touches this repository?

    Look forPut build and test commands and coding conventions in a GEMINI.md at the repository root. Gemini CLI combines the global ~/.gemini/GEMINI.md, the workspace files, and files it finds next to the code it reads, and sends them with every prompt. Set context.fileName to read an existing AGENTS.md as well.

  2. Match the approval mode to the task

    How much should the agent do before it asks?

    Look forThe default mode asks before each tool call, auto_edit approves file edits only, and plan is read-only. YOLO mode approves every action and exists only as a command-line flag. Start unfamiliar work in plan mode, then switch to default once you approve the plan.

  3. Keep an undo path

    Can an engineer undo an agent edit without rewriting the team's Git history?

    Look forSet general.checkpointing.enabled to true in the settings you ship, because it is off by default. Before each approved file change, Gemini CLI snapshots the project to a shadow Git repository under ~/.gemini/history, and /restore returns files and conversation to that point.

  4. Tie the task to a check

    What proves the change works?

    Look forName the failing test, build command, or acceptance check in the prompt. Alexandre Touret's Quarkus upgrade ran until the existing tests passed. Without a check, the agent can report a success it did not reach. One Hacker News commenter watched it raise a test to 100% coverage and then delete the test.

  5. Review before merge

    Who reads the diff, and against which standard?

    Look forReview every agent change at the bar you apply to human code, and commit often so a bad edit is cheap to undo. Read the build and test output yourself. XDA Developers' Adam Conway watched Gemini CLI declare a failed cross-compile a success.

  6. Watch the request count

    How quickly does a working session use the daily cap?

    Look forRun /stats in each session. Code Assist Standard allows 1,500 model requests per user per day and Enterprise 2,000, shared with agent mode in the IDE, and one prompt can make several requests. Check which model served each run too. In September 2026 a team running Gemini CLI headless found that requests for newer model IDs were silently served by Gemini 3.5 Flash, and caught it only by diffing --debug output.

Questions to ask vendors

  1. Which repositories have a GEMINI.md, and who keeps it current when the build changes?
  2. Which approval mode is the team default, and who may run YOLO mode, on which machines?
  3. Is checkpointing on in the settings file every engineer receives?
  4. Which tasks must name a passing test before the agent may call them done?
  5. What does an engineer do when a session reaches the daily request cap?

Red flags

  • Engineers running --yolo in shells that hold production credentials.
  • No GEMINI.md, so each engineer restates conventions in prompts and gets different code.
  • Agent changes merged on the strength of the agent's own summary.
  • No stop rule for sessions that keep editing tests to make them pass.

Products in this piece

Sources

Official documentation
7
Public source
4
  1. Gemini CLI docs: Project context (GEMINI.md)Official documentationgeminicli.com
  2. Gemini CLI docs: Configuration referenceOfficial documentationgeminicli.com
  3. Gemini CLI docs: CheckpointingOfficial documentationgeminicli.com
  4. Gemini CLI docs: Quota and pricingOfficial documentationgeminicli.com
  5. Gemini for Google Cloud: Quotas and limitsOfficial documentationdocs.cloud.google.com
  6. Gemini Code Assist docs: Gemini Code Assist Standard and Enterprise subscriptionsOfficial documentationdocs.cloud.google.com
  7. Gemini CLI docs: Headless modeOfficial documentationgeminicli.com
  8. Alexandre Touret: Streamlining development with Gemini CLI, a hands-on review (Sep 1, 2025)Public sourceblog.touret.info
  9. Hacker News comment by ryoshu on Gemini CLI GitHub Actions (Aug 7, 2025)Public sourcenews.ycombinator.com
  10. XDA Developers: I tried out Google's new Gemini CLI (Aug 1, 2025)Public sourcexda-developers.com
  11. GitHub comment by Gerry Burde: newer model IDs silently served by Gemini 3.5 Flash (Sep 5, 2026)Public sourcegithub.com

Keep reading

  1. Buyer guideGemini CLI System Settings ChecklistSix steps for teams taking Gemini CLI past a pilot, including which data terms govern prompts and how to see cost per engineer.
  2. Buyer guideGemini CLI or Antigravity CLI: Planning the DecisionCode Assist sign-in to Gemini CLI ends with each contract, while paid API keys keep working. Set every team a move date to Antigravity CLI ahead of its last renewal.
  3. Buyer guideGemini CLI in Your GitHub Review WorkflowPull requests waiting on reviewers and issues nobody has labeled: how to set Gemini CLI on both in GitHub Actions, in six steps.
Read the research