# Use Gemini

> Use when delegating bounded coding, audit, or review work to Antigravity CLI (agy binary, post-2026-06-18 successor to gemini-cli) for a THIRD-OPINION pass alongside Claude + codex (3-way cross-validation), OR when work needs Gemini 3.1 Pro reasoning OR Gemini 3.5 Flash speed. Native Windows + WSL tmux wrapper for headless dispatch. Sibling skill of the other CLI-delegation skills.

- Skill: `oimiragieo/use-gemini` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add oimiragieo/use-gemini`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/use-gemini/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/use-gemini

---


# Use Gemini / Antigravity CLI

## CLI status (as of 2026-05-24)

**gemini-cli is RETIRED 2026-06-18 for consumer (Pro/Ultra/free) accounts.** `agy` (Antigravity CLI) is the designated successor. Enterprise/Google Cloud accounts: gemini-cli continues indefinitely via paid API keys.

Install `agy`:

Follow the vendor's current installation instructions at
[antigravity.google/cli](https://antigravity.google/cli). Prefer a versioned
artifact and verify any checksum or signature the vendor publishes; do not pipe a
mutable network response directly into PowerShell. After installation, `agy install`
registers shell integration when the binary is not already on `PATH`.

**🚨 PATH bug on install**: if `agy` doesn't resolve after install, add a shim to `$PROFILE`:
```powershell
Add-Content $PROFILE "`nfunction agy { & '${HOME}\AppData\Local\agy\bin\agy.exe' @args }"
. $PROFILE
```
Auth carries over from gemini-cli OAuth. MCP servers: run `agy plugin import gemini` to migrate; note `mcp_config.json` is now a separate file and remote server fields use `serverUrl` instead of `url`.

## Model picker (agy, Google AI Ultra tier — picker confirmed verbatim 2026-05-29; re-confirmed 2026-07-01)

Display names are the **exact** strings accepted by `settings.json` and by the
`--model` flag in agy v1.0.14+. The wrapper retains its settings-based fallback
for older versions. The 8 rows below are the picker snapshot from 2026-07-01.

| Display name (exact string for settings.json) | Effort | Status | Best for |
|---|---|---|---|
| `Gemini 3.5 Flash (High)` | High | ✅ **DEFAULT** · **← current agy selection (2026-07-01)** | Agentic coding, tool use, bulk audits — beats 3.1 Pro on Terminal-Bench 76.2% vs 70.3% |
| `Gemini 3.5 Flash (Medium)` | Medium | ✅ Available (now in `agy_dispatch.sh` VALID_MODELS) | GA default effort (3.5 Flash GA ships Medium, not High — see GA-change note below). Mid-cost agentic work |
| `Gemini 3.5 Flash (Low)` | Low | 🟡 Untested | Fast cheap lookups |
| `Gemini 3.1 Pro (High)` | High | ✅ Verified | Hard reasoning, GPQA-class (94.3%), ARC-AGI-2 (77.1%), 128k retrieval |
| `Gemini 3.1 Pro (Low)` | Low | 🟡 Untested | Pro reasoning at lower cost |
| `Claude Opus 4.6 (Thinking)` | Thinking | ✅ Verified | Anthropic routing via one Google OAuth |
| `Claude Sonnet 4.6 (Thinking)` | Thinking | 🟡 Untested | Same provider as Opus — likely works |
| `Open-Weights 120B (Medium)` | Medium | ❌ Silently falls back to Gemini | That open-weights model isn't included in Google AI Ultra tier |

**🚨 Gemini 3.5 Flash GA change**: default thinking effort changed from `high` to `medium` (silent regression vs 3-flash-preview). Set `thinking_level: "high"` explicitly in API calls to maintain prior quality. **3.5 Flash limitation**: does NOT support Computer Use; dropped image/audio Live API output vs 3 Flash. **128k regression**: 3.5 Flash MRCR v2 at 128k = 77.3% vs 3.1 Pro 84.9% — if long-context retrieval matters, use 3.1 Pro.

**Model selection: `--model` flag (v1.0.14+) OR settings.json.** As of agy **v1.0.14** there IS a `--model` CLI flag (`agy -p "..." --model "Gemini 3.5 Flash (High)"`) — verified in `agy --help`. `agy_dispatch.sh` still uses the atomic settings.json swap (it predates the flag and works either way); a future wrapper simplification can pass `--model` directly and drop the swap. The legacy settings.json method (needed on ≤v1.0.1):
```powershell
$cfg = Get-Content ~/.gemini/antigravity-cli/settings.json -Raw | ConvertFrom-Json
$cfg.model = "Gemini 3.1 Pro (High)"
$cfg | ConvertTo-Json -Depth 10 | Set-Content ~/.gemini/antigravity-cli/settings.json -Encoding UTF8
```
The `agy_dispatch.sh` wrapper handles this per-call with atomic backup/restore.

**"Who made you?" identity test** (verify any new model entry routes correctly):
```bash
echo "Who created you? One word: Google, Anthropic, or OpenAI." | \
  wsl.exe -d Ubuntu -- bash /mnt/c/Users/you/.claude/skills/use-gemini/agy_dispatch.sh --model "DISPLAY NAME" -
```

## 🚨 No-TTY subprocess hang — PARTIALLY RESOLVED (workaround works; binary bug OPEN)

**Bug**: `agy -p` from a non-TTY subprocess (Claude Code PowerShell wrapper, CI, redirect) silently emits empty stdout (exit 0) on Windows, OR hangs indefinitely on macOS. `--print-timeout` is non-functional on macOS. This is tracked as open issue #76 in google-antigravity/antigravity-cli (confirmed on v1.0.1 too). PR #1 (conhost ConPTY fix) is in flight but not yet merged as of 2026-05-24.

**✅ VERIFIED (2026-07-01), agy v1.0.14** (was v1.0.1 when the bug was last confirmed): `agy.exe` is a Windows binary at `%LOCALAPPDATA%\agy\bin\agy.exe` and works great **interactively** in a real PowerShell console — `PS> agy -p "what is todays date?"` → `Today's date is July 1, 2026.` **NEW: v1.0.14 has a `--model` CLI flag** (`--model "Gemini 3.5 Flash (High)"`), so the settings.json-swap dance is no longer needed for interactive use.

**BUT the no-TTY bug PERSISTS for direct HEADLESS/subprocess dispatch — tested 3 ways, all fail:** `powershell.exe -Command "& agy -p ..."` spawned from bash → **empty stdout**; `Start-Job { agy -p }` → **empty**; `winpty agy -p ...` → **`stdin is not a tty`**. The reason: a non-interactive dispatch has NO controlling terminal, so neither `powershell.exe` nor `winpty` can derive a PTY — and agy with no PTY emits empty stdout (exit 0). A self-allocating PTY is required: use Windows-native ConPTY (workaround B) as the primary path, with WSL `tmux` (workaround A) as the fallback. Interactive-console success does NOT transfer to direct non-interactive dispatch. (agy is genuinely a Windows/PowerShell binary — the WSL hop is purely a PTY shim, not a Linux dependency.)

**Workaround A — WSL tmux (`agy_dispatch.sh`)**: run agy.exe inside a detached tmux pane in WSL, which allocates a real PTY. Wrapper v2 supports per-call `--model` with atomic settings.json backup/restore. Requires any WSL distro with `tmux`.

### ✅ Workaround B — `conpty-run.exe` (Windows-native, NO WSL) — VERIFIED 2026-07-01

A tiny Go binary that runs any command inside a Windows **ConPTY** pseudo-console (`CreatePseudoConsole`, Win10 1809+), captures the child's output, strips VT/ANSI escape noise, and prints clean text to stdout. This is the self-allocating-PTY equivalent of tmux, but pure Windows — **no WSL, no controlling terminal needed.** Source ships in this skill's `conpty-run/` dir (`main.go`, uses `github.com/UserExistsError/conpty` and `golang.org/x/sys/windows`); build it once with **Go 1.25.12** using `go build -trimpath -o conpty-run.exe .` (no binary is committed — see that dir's README).

**Usage (works headless from bash, PowerShell, cron — any non-interactive context):**
```
conpty-run.exe "${HOME}\AppData\Local\agy\bin\agy.exe" -p "PROMPT" --model "Gemini 3.5 Flash (High)" --print-timeout 120s
```
Env: `CONPTY_RUN_TIMEOUT=<sec>` (overall child kill, default 300, maximum 86400); `CONPTY_RUN_MAX_OUTPUT_BYTES=<bytes>` (default 16 MiB, maximum 64 MiB); `CONPTY_RUN_RAW=1` (skip ANSI stripping); `CONPTY_RUN_COLS`/`CONPTY_RUN_ROWS` (each `1..32767`). Output overflow terminates the child, emits no partial output, and exits 125.

**Proof (2026-07-01, spawned from bash — the exact context where powershell.exe 5.1, pwsh 7, Start-Job, and `winpty` all returned EMPTY):**
- `conpty-run.exe <agy> -p "respond with exactly: pong" ...` → `pong`
- `conpty-run.exe <agy> -p "what is today's date?" ...` → `Today's date is July 1, 2026.` (clean, no escape residue)

**Why it works where powershell.exe/pwsh/winpty don't:** ConPTY (via `conpty.Start`) *self-allocates* a pseudo-console and attaches the child to it — it does NOT inherit/derive from a parent TTY. A bash-spawned `powershell.exe -Command "agy -p"` has no console → agy sees `isatty()==false` → empty stdout. `winpty` needs an existing controlling terminal to inherit (headless has none → `stdin is not a tty`). Only a self-allocating PTY works headless: **WSL tmux (workaround A) or ConPTY (workaround B).** PowerShell *edition* (5.1 vs 7.5) makes no difference — verified both empty.

**Rebuild:** `cd conpty-run && go build -trimpath -o conpty-run.exe .` (Go 1.25.12 on PATH; `CGO_ENABLED=0`).

**Migration note:** `conpty-run.exe` lets the thinktank Google seat drop the WSL dependency — dispatch agy via `powershell.exe -Command "& 'conpty-run.exe' '<agy.exe>' -p ... --model ... --add-dir ..."` (or bash directly). Recommended rollout: conpty-run as PRIMARY with `agy_dispatch.sh` (WSL) as documented FALLBACK, until conpty-run has a few live-council runs under its belt.

Canonical invocation (from Claude Code's Bash tool):
```bash
# Basic:
MSYS_NO_PATHCONV=1 wsl.exe -d Ubuntu -- bash \
  /mnt/c/Users/you/.claude/skills/use-gemini/agy_dispatch.sh \
  "Your prompt here"

# Per-call model selection:
MSYS_NO_PATHCONV=1 wsl.exe -d Ubuntu -- bash \
  /mnt/c/Users/you/.claude/skills/use-gemini/agy_dispatch.sh \
  --model "Gemini 3.1 Pro (High)" \
  "Audit this argument for logical holes."

# Stdin for prompts with awkward quoting:
echo "Your prompt" | MSYS_NO_PATHCONV=1 wsl.exe -d Ubuntu -- bash \
  /mnt/c/Users/you/.claude/skills/use-gemini/agy_dispatch.sh -
```

`MSYS_NO_PATHCONV=1` is REQUIRED from MSYS bash (prevents `/mnt/c/...` path mangling).

**Wrapper env-var overrides**: `AGY_PATH`, `AGY_TIMEOUT` (default 300s), `AGY_PTY_WIDTH`/`AGY_PTY_HEIGHT`, `AGY_SETTINGS_PATH`, `AGY_ALLOW_UNTESTED=1`.

**Exit codes**: 0 success / 2 empty-prompt / 3 agy.exe missing / 4 tmux missing / 5 known-fallback model / 6 model not in validated list / 7 empty model / 8 settings.json missing / 9 model-field write verify failed / 124 timeout.

**🚨 New gotcha (agy v1.0.0, Issue #48)**: each `-p` invocation leaks a zombie `agy.exe` process (~113 MB RSS). For batch dispatch sessions, periodically check `Get-Process agy` and kill stale instances.

**Headless Linux auth gotcha (Issue #53)**: keyring silent-fail + timezone skew loop on non-UTC servers. Fix: `GEMINI_FORCE_FILE_STORAGE=true TZ=UTC agy -p "test"`.

## Headless tool use (agy v3 wrapper, `--allow-tools` flag)

Pass `--allow-tools` to wrapper → sets `--dangerously-skip-permissions` on inner agy call. Unlocks full tool catalog: `view_file`, `list_dir`, `grep_search`, `replace_file_content`, `write_to_file`, `run_command`, `read_url_content`, `search_web` (built-in, no MCP needed), `invoke_subagent`.

**🚨 CWD gotcha**: agy cwd is always hardcoded to `~/.gemini/antigravity-cli/scratch`. Pass absolute Windows paths explicitly:
- ✅ `view_file C:\Users\u\foo\bar.py`
- ❌ "read the file in your workspace" / "look in current directory"

`--add-dir /mnt/c/path` makes files accessible; wrapper auto-converts WSL paths to Windows format.

## Persona contamination — root-caused (2026-05-19)

If agy returns off-topic preamble or roleplay responses: check `~/.gemini/gemini.md` for stale system-prompt instructions. agy inherits the entire `~/.gemini/` config tree including rules files. Delete or update any stale file. Audit `~/.gemini/` after any major workflow change.

## Core rule

**agy is a bounded peer reviewer + bounded implementation worker. Claude owns the plan, the prompt file, the audit synthesis, the tests, the commits, and the final answer to the user.**

Three model families = three independent calibrations. For high-stakes diffs (billing, auth, webhooks, migrations), run Claude + codex + agy in parallel; the diff between their outputs is where each model's blind spots show.

## When to use / skip

| Use agy | Use codex | Use Claude Agent subagent |
|---|---|---|
| Third opinion to break Claude+codex tie | Second opinion to break a Claude tie | When Claude's tool context (existing reads) is already loaded |
| Frontier reasoning review (Gemini 3.1 Pro) | Default frontier (gpt-5.5) | Reviews where rubric is in this codebase's CLAUDE.md only |
| Ultra-fast bulk audits (3.5 Flash 289 tok/s) | Long-horizon coding (gpt-5.4) | Tasks needing THIS conversation's context |
| Audit-only: `--approval-mode plan` (gemini-cli) / `--sandbox` (agy) | Write specs with `-y` | Trivial edits — Edit tool is faster |

**Don't use agy for**: small targeted edits, live debugging requiring mid-flight context, cold-start round-trip > 30s where Claude is already loaded.

## 429 / capacity-exhausted

Gemini 3.1 Pro hits `MODEL_CAPACITY_EXHAUSTED` at peak. CLI auto-retries with backoff but ≥4 retries = swap model. Distinguish: `MODEL_CAPACITY_EXHAUSTED` = server-side (swap model), `rateLimitExceeded` = user-tier quota (wait). Default to 3.5 Flash for thinktank/audit dispatches — far less capacity-constrained.

## Approval modes (gemini-cli era; agy equivalent = `--sandbox`)

| Mode | Effect | When |
|---|---|---|
| `--approval-mode plan` | Read-only — no writes, no shell mutations | Audits (use this by default) |
| `--approval-mode auto_edit` | Auto-approves edits, prompts for shell | Bounded write specs |
| `-y` / `--yolo` | Auto-approves everything | Write specs with no-commit constraint only |
| `default` | Prompts every tool call | NEVER for headless — blocks forever |

## Workflow (abbreviated)

1. Identify task: audit (plan mode) vs bounded write (-y with explicit spec)
2. Verify `agy` resolves: `agy --version` + `agy -p "say only OK" --dangerously-skip-permissions`
3. Write spec to `.claude/gemini_task_<name>.md` (NOT `.tmp/` — needs to be discoverable in PRs)
4. Launch via `agy_dispatch.sh` wrapper with appropriate `--model`
5. Continue Claude work in parallel (agy sessions: 5-15 min at 3.1-pro, 2-5 min at 3.5-flash)
6. Read audit doc (not the log), diff against codex findings, synthesize

**Spec required fields**: working dir, model (explicit), branch+repo, files to review, orchestrator's existing claims, severity rubric, output file path, "Do NOT git commit/push", "Do NOT switch model mid-session", "Do NOT continue to interactive mode", done-criteria line.

**Critical launch pattern** (stdin spec avoids quoting hell):
```bash
nohup agy -p "Read spec. Execute. Save to <output>. Exit when done." \
  --dangerously-skip-permissions \
  < .claude/gemini_task_<name>.md \
  > /tmp/agy_logs/<name>.log 2>&1 &
# (via agy_dispatch.sh wrapper for non-TTY contexts)
```

## Guardrails

- Never paste raw markdown into bash -lc — use stdin-from-file
- No backticks in `-p` prompt string (evaluated by host shell)
- Don't pass API keys in the prompt — agy reads from settings or env
- Model-name typo silently kills session or falls back — sanity-test string first
- MCP tool double-registration warnings at startup = noise, not errors
- Extension hooks load errors = non-blocking noise (`agy extensions remove <name>` to clean)
- `--approval-mode plan` + `-w` (worktree) as belt-and-suspenders for write-mode specs

## Red flags — STOP and rewrite the spec

"Audit the codebase" / "Find bugs" (no rubric) / "Validate the fix" (no file:line) / "Suggest improvements" / Multi-step plans without explicit sequencing.

## Three-way audit synthesis

- 3/3 agree → ship fix, low investigation cost
- 2/3 agree → investigate dissenter (may be noise OR may have found context-specific issue)
- 1/3 alone → high noise risk; verify before acting

## agy invocation flags quick-ref

| Use case | Flag |
|---|---|
| Headless one-shot | `agy -p "task"` or `agy --print "task"` |
| Sandbox (read-ish) | `agy --sandbox -p "task"` |
| Auto-approve all | `agy --dangerously-skip-permissions -p "task"` |
| Add workspace dir | `agy --add-dir /path -p "task"` (repeatable) |
| Conversation continuation | `agy -c` (most recent per cwd) or `agy --conversation <id>` |
| Timeout | `agy --print-timeout 10m -p "task"` (non-functional on macOS) |

## Cross-references

- codex — sibling second-opinion CLI (gpt-5.5 default)
- cursor — bounded write work in WSL on auto-model
- `use-claude-in-chrome` — when agy needs an authenticated SaaS session; dispatch via this skill rather than agy's headless chrome-devtools
- Gemini MCP servers (registered in `~/.gemini/settings.json`): chrome-devtools, MCP_DOCKER, shadcn, Exa, Ref — auto-available to agy sessions
- Conversation state per-cwd: `~/.gemini/antigravity-cli/cache/last_conversations.json` maps cwd → conversation ID; `agy -c` resumes per cwd
- Per-conversation brain/transcript: `~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl`

## Full per-entry rationale → `@SKILL.md.bak`

The .bak (835 lines, ~38 KB, 2026-05-24) contains: full installer PATH dedup one-liner, complete slash-command reference table, full headless tool catalog table, full incident narrative (persona contamination), complete settings.json auth-warning receipt, conversation persistence details, detailed gemini-cli-era launch patterns (nohup/powershell invocation), full approval-mode flag descriptions, full spec template with all fields, agy capabilities delta vs gemini-cli. Load on demand for any of these.

**Exa-surfaced updates not yet in .bak (2026-05-24 research)**:
- 🚨 Issue #76 (last confirmed v1.0.1): no-TTY empty-stdout bug — **installed agy is now v1.0.14; re-verify `agy -p` in a real PowerShell console (ConPTY fix PR #1 may have merged)**. `--print-timeout` also non-functional on macOS.
- 🚨 Issue #48: `agy -p` leaks zombie process per invocation — check `Get-Process agy` in batch sessions
- Issue #53: headless Linux auth loop — `GEMINI_FORCE_FILE_STORAGE=true TZ=UTC` workaround
- Gemini 3.5 Flash GA: default effort `high` → `medium` (silent regression); 128k context regression vs 3.1 Pro; no Computer Use
- MCP migration: `mcp_config.json` separate file; remote server `url` → `serverUrl`