Gemini CLI — Google's Free Terminal Coding Agent

In short: Install Gemini CLI next to Claude Code and build a measured routing layer: a free commit-message and PR-description drafter, a large-context repo summarizer that feeds Claude, and a grounded-research helper, each wired through gemini -p --output-format json.

GitHub: https://github.com/google-gemini/gemini-cli Stars: ~101,000 (forks: ~13,000) License: Apache 2.0 Language: TypeScript (Node.js) Repo: https://github.com/google-gemini/gemini-cli

What it is

Gemini CLI is Google's official open-source terminal-first AI coding agent. It's the direct Claude Code / Codex CLI competitor from Google, built on the Gemini 2.5 family of models. Unlike most "AI in the terminal" projects, it has a genuinely usable free tier: sign in with a personal Google account and you get 60 requests per minute and 1,000 requests per day against Gemini 2.5 Pro at no cost. That alone makes it one of the highest-value free developer tools shipped in the last year.

It's an interactive REPL agent with tool use — it can read files, run shell commands, edit code, fetch URLs, search Google, and call MCP servers. Same basic loop as Claude Code: you type a request, it plans, it runs tools, it edits, you review, rinse, repeat.

Where Claude Code is polished and opinionated (tightly integrated with Anthropic's sandbox model), Gemini CLI is more raw and Google-flavored. It's a real, working agent — not a toy — but it leans on Google's strengths (huge context windows, cheap Flash tier, web grounding) rather than Anthropic's (tool discipline, long-horizon coherence).

How it works

At runtime Gemini CLI is a Node.js TUI that:

1. Loads context from a GEMINI.md file in the current directory (same idea as CLAUDE.md)
2. Builds a system prompt with tool schemas for built-in tools (read, write, shell, glob, grep, web fetch, google search, memory)
3. Streams tokens from Gemini 2.5 Pro (default) or Flash (-m gemini-2.5-flash) via the chosen auth backend
4. Parses tool calls, prompts you for approval on destructive actions, runs them, feeds results back
5. Checkpoints conversations so you can resume

Built-in capabilities worth calling out:

• Google Search grounding — free live web search baked into the agent (Claude Code has to hit WebFetch/WebSearch separately)
• MCP support — add servers in ~/.gemini/settings.json, same protocol as Claude Code, so your existing MCP catalog (Figma, GitHub, Playwright, Context7) works
• --include-directories — explicit multi-root context (gemini --include-directories ../lib,../docs)
• Non-interactive mode — gemini -p "prompt" --output-format json for scripting and CI, with stream-json for piping
• GitHub Action — official action for running Gemini CLI in CI

System requirements

• Node.js 20+ (Node 22 LTS recommended)
• A Google account (free tier) OR a Gemini API key OR Vertex AI credentials
• Any OS with a terminal; works identically on macOS, Linux, WSL2, Windows
• Zero GPU/local model requirements — everything runs in Google's cloud

Quick start

Install via npm (simplest on a dev machine that already has Node):

npm install -g @google/gemini-cli
gemini

Or run with zero install:

npx @google/gemini-cli

macOS/Linux alternates:

brew install gemini-cli           # Homebrew
sudo port install gemini-cli      # MacPorts

On first run it prompts you to authenticate. Pick "Sign in with Google" for the 1K/day free tier — a browser tab opens, you sign in, token is stored in ~/.gemini/. Done.

Switch models mid-session or at launch:

gemini -m gemini-2.5-flash        # much cheaper/faster, still strong
gemini -m gemini-2.5-pro          # default, best reasoning

Add MCP servers by editing ~/.gemini/settings.json:

{
  "mcpServers": {
    "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] },
    "context7":   { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }
  }
}

Drop a GEMINI.md in any repo to pin project context (coding standards, architecture notes, gotchas) — it's loaded automatically, same pattern as CLAUDE.md.

Non-interactive one-shot (great for scripts and hooks):

gemini -p "summarize the changes in the last 5 commits" --output-format json

Gemini CLI vs Claude Code — honest comparison

What Gemini CLI is better at:

• Massive context tasks (read entire repos, summarize huge log files, refactor across dozens of files) — the 1M token window matters
• Free grunt work you don't want to burn Claude credits on (docs, boilerplate, commit messages, codegen from a spec)
• Scripted/batch automation where cost would add up
• Research tasks that need live web grounding without extra plumbing

What Claude Code is better at:

• Long multi-turn agentic work (the RPI/crank flywheel, subagent-driven dev, complex debugging)
• Tool-heavy workflows where tight permission control matters
• Anything where you've already invested in skills, hooks, and the AgentOps stack

Known limitations

• Free tier is personal Google only — Workspace accounts often can't use it (admin policy blocks sign-in)
• 1K/day sounds like a lot but a single long agent session can chew through 100+ requests; heavy days hit the cap
• Tool discipline is weaker than Claude Code — it will sometimes run commands you didn't approve flow for, or stop and ask where Claude would have continued
• Less mature ecosystem: no native equivalent to the superpowers/AgentOps skill layer
• Model knowledge cutoff and training data bias differs — good Gemini answers on Google Cloud/Android/Flutter, relatively weaker on niche TS ecosystems where Claude shines

How to use both together

The trick isn't "which one wins" — it's routing. Claude Code stays as the primary agent for high-value multi-step work (complex refactors, platform work, anything RPI-shaped). Gemini CLI becomes the free workhorse for:

1. Commit/PR drudgery — wire gemini -p into a git hook or the commit-commands skill to auto-draft commit bodies, PR descriptions, changelogs. Zero Claude credit burn.
2. Large-context reads — whenever a task needs to ingest an entire repo or huge log, hand it to Gemini first for a summary, then feed the summary to Claude. The 1M window is free leverage.
3. Research + grounded web search — /research-style tasks, documentation lookups, "what's the latest on X library" — Gemini's Google grounding is free and built-in.
4. Codegen for throwaway scripts — one-shot shell scripts, data munging, format converters. gemini -p "write a bash script that..." → done.
5. CI jobs — the official GitHub Action runs Gemini CLI on PRs for lint-style review, doc checks, test generation, without burning Anthropic quota.
6. Second opinion / council member — in /council-style multi-model workflows, Gemini is a free extra vote alongside Claude and Codex.
7. Fallback during Anthropic rate limits or outages — same terminal muscle memory, keeps you unblocked.

Practical setup: install it globally, sign in with Google, add the same MCP servers you use in Claude Code so context transfers cleanly, and keep a second terminal open for Gemini-handled tasks. Treat it like the free tier of a second brain.

What we could build with it

• A free commit/PR writer hook that runs gemini -p on every commit and populates the body automatically
• A large-repo summarizer that indexes a codebase into GEMINI.md chunks so downstream Claude sessions start with perfect context
• A research skill that uses Gemini's grounded search for fact-gathering, then hands structured results to Claude for synthesis
• A CI reviewer using the official GitHub Action to do first-pass review on every PR for free before human/Claude review
• A dual-agent council where Claude and Gemini both critique a plan before implementation (poor-man's /council)
• A terminal chatbot for docs/support that only needs to answer questions and can run fully on the free tier

Bottom line

Gemini CLI is the most valuable "free developer tool that's actually good" released recently. It doesn't replace Claude Code for real engineering work — but it makes 30-40% of what you currently spend Claude credits on essentially free. The right move is to install it alongside Claude Code and route drudgery to it by default.

Prompt system — run this yourself

Everything below is pasteable into Claude Code, Claude, or any agent. Use the one-shot when you want the whole result in one run; use the step prompts when you want to steer. Every step carries its own audit, and the gap audit at the end makes the agent find and fill what it missed.

Mission. Install Gemini CLI next to Claude Code and build a measured routing layer: a free commit-message and PR-description drafter, a large-context repo summarizer that feeds Claude, and a grounded-research helper, each wired through gemini -p --output-format json. Done means every route has a quota-aware wrapper with a Claude fallback, the guide's free-tier and quality claims have been re-checked against Google's current quota page and a small blind comparison on your own tasks, and you know, with numbers, which tasks Gemini handles acceptably and which stay on Claude.

1 · Deeper, not bigger

Before running anything, make the task deeper rather than larger. Ask: what would a top professional do here that I am not asking for; what is the rawest material; which methods and tools; what, other than the model or me, proves it right. Then ask for exactly that.

• What a top professional would do (that you didn't ask for): A developer-tools lead would not adopt a second agent on vibes; they would define the routing decision as an evaluation problem. They would pick 20-30 real tasks from their own history in each candidate category (commit bodies, PR descriptions, repo summaries, docs lookups, throwaway scripts), run both agents blind, and grade with a rubric or with tests. They would re-verify the free-tier numbers (the guide says 60 requests/min and 1,000/day on Gemini 2.5 Pro with a personal Google account) on Google's live quota page because these limits have changed more than once, and they would read the data-use terms for the free tier before sending private code.
• Rawest material to start from: The repo itself at github.com/google-gemini/gemini-cli (docs/ folder: cli/commands, configuration, headless mode, sandbox, checkpointing, tools, MCP server setup); the CHANGELOG and release notes for the version you install; Google's current quotas and pricing pages for the Gemini API and Gemini Code Assist, plus the terms covering how free-tier prompts may be used; the official GitHub Action repo (google-github-actions/run-gemini-cli); your own git log (git log -n 200 --format='%H%n%B') as the corpus of real commit messages to compare against; and the JSON that gemini -p --output-format json actually returns, captured to disk, including its stats block.
• Methods and tools: npm install -g @google/gemini-cli (pin the version); gemini -p ... --output-format json and stream-json; -m gemini-2.5-flash versus default; --include-directories; GEMINI.md context files; ~/.gemini/settings.json for mcpServers; /stats and /memory show inside the REPL; --sandbox for untrusted runs; jq for parsing; a bash or Python wrapper with retry and exponential backoff on 429 and fallback to claude -p; prepare-commit-msg git hook for commit drafting; a blind A/B grading sheet (CSV) with a 1-5 rubric; tiktoken or the API's usage fields for token counts.
• What proves it right (other than you or the model): The oracles are your repo and blind grading: (a) a blind A/B on 25 historical commits, where you or a teammate rate Gemini's and Claude's drafted commit bodies against the diff without knowing which is which; (b) for the repo summarizer, a set of 15 factual questions about the codebase with answers checked by grep, answered by Claude with and without the Gemini summary; (c) for generated scripts, shellcheck plus running them on fixture inputs; (d) Google's quota page and the call log showing requests per day stayed under the cap.

Rewritten prompt — ask for exactly that:

Act as a developer-tools lead evaluating Gemini CLI as a free second agent beside Claude Code. First, install a pinned version of @google/gemini-cli, record `gemini --version`, and read its docs folder for headless mode, output formats, settings.json, sandbox, and MCP. Check Google's current quota and terms pages and record today's actual free-tier limits and data-use terms for personal accounts; flag any difference from '60 req/min, 1,000/day on 2.5 Pro'. Capture the real JSON shape of `gemini -p 'hello' --output-format json`. Then build bin/gem, a wrapper that runs a prompt through Gemini with a model flag, logs latency, tokens, and status to ~/.gemini-calls.csv, retries 429s with backoff, and falls back to `claude -p` after two failures. Use it for three routes: (1) a prepare-commit-msg hook drafting commit bodies from `git diff --cached`; (2) a repo summarizer writing docs/REPO_SUMMARY.md using --include-directories; (3) a grounded research helper that returns claims with source URLs. Evaluate each route blind against Claude on 20-30 tasks from my own history with a 1-5 rubric, and run 15 grep-checkable codebase questions to test the summarizer. Return a routing table (task, route to, evidence), the wrapper, the hook, the eval CSVs, and a list of guide claims that did not hold.

2 · One-shot prompt

ROLE AND STANCE
You are a developer-tools lead deciding, with evidence, which of this developer's tasks can move from Claude Code to Google's free Gemini CLI. You treat the guide's claims as hypotheses. You protect private code and secrets, and you assume quotas and model names have changed since the guide was written.

CONTEXT
- Gemini CLI: github.com/google-gemini/gemini-cli, Apache 2.0, Node 20+. Install `npm install -g @google/gemini-cli` or `npx @google/gemini-cli`. Context file GEMINI.md. Settings in ~/.gemini/settings.json (mcpServers block, same protocol as Claude Code). Headless: `gemini -p "..." --output-format json` or `stream-json`. Models via `-m` (guide: gemini-2.5-pro default, gemini-2.5-flash cheaper). Multi-root context: `--include-directories ../lib,../docs`. Official GitHub Action for CI. Built-in Google Search grounding.
- Guide claims to TEST: (1) free tier is 60 req/min and 1,000 req/day on 2.5 Pro with personal Google sign-in; (2) context window ~1M tokens versus ~200K for Claude; (3) Workspace accounts often cannot use the free tier; (4) one long agent session can use 100+ requests; (5) grounding is free and built-in.
- Proposed routes from the guide: commit/PR drafting, large-context reads summarized for Claude, grounded research, throwaway script codegen, CI review via the Action, a second vote in /council-style reviews, fallback during Anthropic outages.

HARD CONSTRAINTS
- Before sending any repository content, read the current free-tier data-use terms and record whether prompts may be used for training or human review. If they may, do not send code from private or client repos; use only open-source or personal repos and say so.
- Never pass .env files, keys, or credential directories to Gemini. Add them to .geminiignore (verify the file name is supported in the docs) and exclude them in every wrapper call.
- Pin the CLI version. Log every call. Stay at least 20 percent under the daily cap during evaluation.
- No route goes live until its blind evaluation is done.

ORDERED DELIVERABLES
1. ground-truth.md: installed version, auth method, today's quotas and model names from Google's pages (with URLs and access date), data-use terms summary, the exact JSON schema returned by --output-format json (field names, stats block), and verdicts on claims 1-5 that can be checked without evaluation.
2. bin/gem: wrapper with -m, timeout, CSV logging (timestamp, route, model, latency ms, input/output tokens if reported, exit status), backoff on 429/RESOURCE_EXHAUSTED, and fallback to `claude -p` after two failures, logging which agent answered.
3. .git/hooks/prepare-commit-msg (installable script) that drafts a body from `git diff --cached` truncated sensibly, only when the message is empty, and never blocks the commit on failure.
4. scripts/repo-summary.sh producing docs/REPO_SUMMARY.md with an architecture map, module list, entry points, and known gotchas, using --include-directories.
5. scripts/research.sh that asks for grounded answers and requires a URL per claim in the JSON output.
6. eval/: commits.csv (25 historical diffs, blind-labelled outputs A/B, scores), summarizer.csv (15 grep-checkable questions answered by Claude with and without the summary, correct y/n), scripts.csv (10 throwaway-script tasks, shellcheck pass, fixture run pass).
7. routing.md: table of task type, route, evidence, fallback.

BUILT-IN GAP ANALYSIS
Before finishing, write gaps.md: claims you could not verify (for example consumption of requests per session if /stats is unavailable headless); routes not evaluated (CI Action, council vote, outage fallback) and what it would take; any case where Gemini ran a command or edit without approval; quota numbers that differed from the guide; any evaluation where sample size is under 15. Fill what you can now: if the Action was not tested, set it up on a throwaway repo and run it once.

SELF-QUESTIONS BEFORE FINISHING
- Did I read today's quota page, or rely on the guide's numbers?
- What do the free-tier terms say about prompt data, and did I respect that for every repo I sent?
- Were graders blind to which agent wrote each commit body?
- Did the summarizer help Claude answer more questions correctly, or just make it faster?
- Did grounded research return real, reachable URLs, and did I spot-check that they support the claims?
- How many requests did one prepare-commit-msg call consume, and what is the daily total at my commit rate?

STOP CONDITIONS
Stop when routing.md is backed by the three eval files and the wrapper and hook are installed. Stop and ask if the terms forbid the user's intended use on private code, if sign-in requires a Workspace admin change, or if the quota is far below the guide's numbers (the routing case may collapse).

RETURN FORMAT
One message: ground-truth table (claim, guide value, verified value, source); file list with one-line usage each; eval summary (route, n, Gemini mean score, Claude mean score, verdict); routing table; gaps.md contents; the daily request budget estimate.

3 · Step-by-step prompts

Step 1 — Ground truth: install, quotas, terms, output schema

Goal: Pin what Gemini CLI actually is today on this machine and under today's terms.

Install a pinned version: `npm install -g @google/gemini-cli@<latest-tag>`; record `gemini --version` and `node --version` (must be 20+). Clone github.com/google-gemini/gemini-cli to repos/gemini-cli and read docs/ for: headless mode and --output-format, settings.json keys, mcpServers, GEMINI.md loading order, ignore files, sandbox, checkpointing, built-in tools, and the GitHub Action. Sign in with the personal Google account. Open Google's current quota/pricing pages for Gemini CLI and Gemini Code Assist and the terms that apply to the free tier; record today's request limits, available models, and whether free-tier prompts may be used to improve products or be read by humans, with URLs and the access date. Run `gemini -p 'Reply with the word ok' --output-format json > ground/hello.json` and document every field, especially any stats or token usage block. Then write ground-truth.md with a claims table: free-tier limits, default model, context window, Workspace restriction, built-in grounding, MCP compatibility; each with guide value, verified value, and source.

Expect: ground-truth.md with a version line, a six-row claims table, a terms summary of 3-5 bullets, and a documented JSON schema; repos/gemini-cli cloned.

Audit before moving on: Every verified value must cite a URL or a file under repos/gemini-cli/docs. If the terms permit training on prompts, mark which repos are off-limits before any later step sends code. If hello.json lacks token counts, note that the CSV log will rely on another source.

Step 2 — Build the quota-aware wrapper with fallback

Goal: One entry point that logs, retries, and falls back to Claude.

Write bin/gem (bash or Python 3 stdlib). Usage: `gem [-m model] [--route name] [--timeout s] [--include dir,...] -- "prompt"` with stdin appended to the prompt if piped. It runs `gemini -p <prompt> --output-format json -m <model>`, parses the response field and any usage/stats fields with jq or json, prints only the response to stdout, and appends a CSV row to ~/.gemini-calls.csv: ISO timestamp, route, model, latency ms, input tokens, output tokens, status, answered_by. Detect quota exhaustion by matching the actual error text or code the CLI emits for HTTP 429 / RESOURCE_EXHAUSTED (trigger it once deliberately with a tight loop on a throwaway prompt if needed, or read the source in repos/gemini-cli for the error shape). Retry twice with backoff of 2 and 8 seconds; then run `claude -p` with the same prompt and set answered_by=claude. Refuse to send any file path matching .env*, *.pem, id_*, or credentials directories. Add a `gem --today` subcommand that prints calls and tokens for the current day against the verified daily cap.

Expect: An executable wrapper, a CSV with test rows, and a demonstration of one fallback to Claude.

Audit before moving on: Run ten calls and confirm ten CSV rows with plausible latency. Simulate a failure (bad model name) and confirm fallback triggers and is logged. Pipe a fake .env path and confirm refusal. If quota detection relies on a guessed string, mark it unverified in gaps.md.

Step 3 — Commit and PR drafting route

Goal: Draft commit bodies and PR descriptions for free, and test quality blind.

Write hooks/prepare-commit-msg: if the commit message file already has non-comment content or the source is merge/squash, exit 0. Otherwise build input from `git diff --cached --stat` plus `git diff --cached` truncated to 3,000 lines with a note if truncated, and call `gem --route commit -m gemini-2.5-flash` (or the current fast model from ground-truth.md) with a prompt asking for a 50-character imperative subject and a body explaining why, wrapped at 72 columns, no marketing words. Write the result into the message file above the comments. Never fail the commit: on any error, exit 0 silently and log. Install it in the current repo. Then evaluate: pick 25 historical commits with `git log -n 200 --no-merges`, regenerate each message from its diff with both gem and `claude -p` using the same prompt, shuffle into A/B pairs with a hidden key, and have the user (or a separate grader subagent given only diff and two candidates) score each 1-5 on accuracy, why-not-what, and length. Save eval/commits.csv. Also add scripts/pr-draft.sh that does the same for `git diff main...HEAD` and prints a PR body.

Expect: Installed hook, pr-draft.sh, eval/commits.csv with 25 rows and mean scores per agent.

Audit before moving on: Check that the hook adds under 5 seconds median to a commit (time ten commits on a scratch branch) and never blocks on failure (break the network and commit). Verify the grader never saw the key. If Gemini's mean is more than 0.5 below Claude's, mark the route 'Claude' in routing.md.

Step 4 — Large-context summarizer route

Goal: Use Gemini's big window to summarize a repo and prove the summary helps Claude answer correctly.

Write scripts/repo-summary.sh <repo>: run gem with `--include-directories` covering src, lib, and docs (exclude node_modules, build outputs, vendored code, and anything matched by the ignore rules), asking for docs/REPO_SUMMARY.md with sections: purpose, architecture map (modules and their dependencies), entry points with file paths, data flow, configuration and env vars by name only, test layout, and known gotchas with file:line references. Record the input size in tokens from the usage fields. Then build eval/summarizer.csv: write 15 factual questions about the repo whose answers can be checked by grep or by reading one file (for example 'which module reads DATABASE_URL', 'what function handles webhook retries'). Ask `claude -p` each question twice: once with no context beyond the repo path and a 2-minute budget, once with REPO_SUMMARY.md prepended. Check each answer against grep and record correct y/n and wall time. Also spot-check 10 file:line references in the summary for existence.

Expect: REPO_SUMMARY.md, input token count, eval/summarizer.csv with 30 graded answers, and a reference-accuracy score out of 10.

Audit before moving on: Any fabricated file path or function name in the summary counts against it; if more than 2 of 10 references are wrong, the route fails until the prompt is tightened and re-run. Confirm no secret values appear in the summary by grepping for key-like patterns.

Step 5 — Grounded research and throwaway script routes

Goal: Test the two remaining cheap routes with checkable outputs.

Write scripts/research.sh '<question>' that calls gem asking for a JSON array of claims, each with text and a source URL, using Google Search grounding. Run it on 8 questions where you can verify the answer (current latest version of three libraries the repo uses, a breaking change in one of them, two API rate limits, one security advisory). For each claim, fetch the URL and mark supported, unsupported, or unreachable; save eval/research.csv. Then pick 10 throwaway-script tasks from shell history or past requests (CSV munging, log grepping, file renaming, JSON reshaping) and generate each with `gem` and with `claude -p` using an identical prompt. Run shellcheck (or ruff for Python) on every output, then run each on a prepared fixture input and compare to an expected output you write first. Save eval/scripts.csv with lint pass, fixture pass, and tokens per agent. Finally, on a throwaway repo, install the official run-gemini-cli GitHub Action with the API key as a repository secret, open a PR with a planted off-by-one bug, and record whether the review catches it.

Expect: eval/research.csv with per-claim support status; eval/scripts.csv with 20 rows and pass rates per agent; one Action run URL with caught or missed.

Audit before moving on: If more than 20 percent of research claims are unsupported by their own URLs, mark the research route as 'leads only, verify before use'. Make sure expected fixture outputs were written before seeing either agent's script; if not, rewrite them and re-grade.

Step 6 — Validate against the oracles and write the gap report

Goal: Turn the evals into a routing decision and list what is still unproven.

Aggregate eval/commits.csv, eval/summarizer.csv, eval/research.csv, eval/scripts.csv, and eval/optional.md. For each route compute n, Gemini mean or pass rate, Claude mean or pass rate, and the difference. Write routing.md, one row per task type: task type, route to (Gemini, Claude, or Gemini-then-Claude-verify), evidence file, fallback, and expected daily request use from ~/.gemini-calls.csv extrapolated to the user's normal week. Compare that daily use to the verified cap from ground-truth.md and state the headroom as a percentage. Write gaps.md listing: guide claims with final verdicts (true, false, changed, unverified) with sources; routes with n under 15; any unapproved action Gemini took during testing; privacy constraints that limit which repos can use which routes; untested items. Recommend whether to keep the prepare-commit-msg hook installed, citing the median latency it added and the commit eval score.

Expect: routing.md with 6-8 rows, a daily budget estimate, and gaps.md with every guide claim resolved.

Audit before moving on: Every routing decision must cite a number from an eval file. If the daily estimate exceeds 80 percent of the cap, mark which route to throttle. If any route had graders who could see the agent label, mark its verdict provisional.

4 · Gap analysis and audit

Run this after the build. It makes the agent enumerate its own claims, mark what is verified, rank the gaps and fix the top ones.

You are auditing a Gemini CLI routing setup built by someone else: bin/gem, a prepare-commit-msg hook, repo-summary.sh, research.sh, eval/*.csv, routing.md, gaps.md. Do not trust routing.md. (1) List every claim made: quotas, data-use terms, wrapper behaviour (logging, backoff, fallback, secret-path refusal), hook safety (never blocks, skips when a message exists), and each route's eval verdict. (2) Verify each: re-open Google's quota and terms pages today, run the wrapper with a bad model and with a .env path, commit with the network down, re-grade five random rows of each eval CSV yourself, and re-check five research URLs. Mark verified, unverified, or false with evidence. (3) Look for silent failures: does the hook ever write an empty or error message into a commit; does the wrapper count a fallback answer as a Gemini success; does the summarizer include ignored directories; do any logs contain secrets. (4) Rank gaps by impact: privacy or secret exposure first, then wrong routing decisions, then friction. Fix the top three now and re-run their checks. Report remaining gaps with the command that reproduces each, and state whether routing.md still holds.

Questions the agent must ask itself before it says done:

• Are the quotas and model names in my notes from Google's page today, or carried over from the guide?
• Do the free-tier terms allow sending this repo's code, and did I enforce that in the wrapper?
• Does the wrapper recognise the actual quota-exhausted error, verified by triggering it or reading the source?
• How many requests does one commit-draft call cost, and what is my weekly total at my commit rate?
• Were the commit graders blind, and did they see the full diff?
• Did the repo summary contain fabricated paths or functions, and how many?
• Did grounded research URLs actually support their claims when opened?
• Did Gemini ever run a shell command or edit without my approval during testing?

5 · What proves it right

• Google's current Gemini CLI quota and terms pages, cited with URL and access date, versus the guide's 60/min and 1,000/day figures.
• Blind A/B grading of 25 historical commits, scored by the user or a grader that never sees the agent label, with means per agent.
• Fifteen grep-checkable codebase questions answered by Claude with and without the Gemini summary, scored against grep output.
• shellcheck/ruff plus fixture runs with expected outputs written in advance for 10 throwaway-script tasks per agent.

6 · Failure modes

• Quota numbers out of date. Tell: 429 errors far earlier in the day than expected. Fix: re-read the quota page, lower the budget, route bulk work to Flash.
• Private code sent under permissive free-tier terms. Tell: terms allow training or human review and client repos were used. Fix: restrict routes to open or personal repos, or use a paid API key with different terms.
• Hook blocks or corrupts commits. Tell: commits hang or contain error text. Fix: timeouts, exit 0 on any failure, only write when the message is empty.
• Summary hallucinates structure. Tell: Claude cites files that do not exist. Fix: require file:line references and spot-check them, re-prompt with stricter instructions.

7 · Agent direction (unattended runs)

Start with ground truth: install a pinned version, clone the repo for docs, and read today's quota and terms pages before sending any code. Use bin/gem for every Gemini call so all usage lands in one CSV. Spawn a separate grader subagent for blind A/B scoring that receives only the diff and two unlabelled candidates; never grade your own pairs. Never pass .env files, keys, or credential directories to either agent, and never echo the Action's API key. Stop and ask if the terms rule out the user's private repos, if sign-in requires a Workspace admin, or if the quota is too small for the routes to matter. Return in chat the claims table, eval summary, routing table, daily budget, and gaps; files go to bin/gem, hooks/prepare-commit-msg, scripts/, eval/, docs/REPO_SUMMARY.md, routing.md, gaps.md, ground-truth.md.

Prompt system updated 2026-10-22 · all prompt systems · JSON