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. 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.

🚨 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" ... → 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):

# 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

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)

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):

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

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