| name | use-gemini |
| description | 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. |
| when_to_use | Third-opinion audit alongside Claude + codex. Math/reasoning-heavy review (Gemini 3.1 Pro GPQA 94.3%). Fast bulk audits (3.5 Flash 289 tok/s). Audit-safe read-only via --approval-mode plan (gemini-cli) or --sandbox (agy). 3-way cross-validation pattern on high-stakes diffs. |
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. 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:
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):
$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):
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" ... → pongconpty-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):
MSYS_NO_PATHCONV=1 wsl.exe -d Ubuntu -- bash \
/mnt/c/Users/you/.claude/skills/use-gemini/agy_dispatch.sh \
"Your prompt here"
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."
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)
- Identify task: audit (plan mode) vs bounded write (-y with explicit spec)
- Verify
agy resolves: agy --version + agy -p "say only OK" --dangerously-skip-permissions
- Write spec to
.claude/gemini_task_<name>.md (NOT .tmp/ — needs to be discoverable in PRs)
- Launch via
agy_dispatch.sh wrapper with appropriate --model
- Continue Claude work in parallel (agy sessions: 5-15 min at 3.1-pro, 2-5 min at 3.5-flash)
- 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):
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 &
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
