antigravity-cli

Antigravity CLI (agy)

agy is Google's terminal coding agent (Antigravity; the successor to Gemini CLI). It runs Gemini, Claude, and open models behind one harness with tools for reading/editing files and running commands. Binary lives at ~/.local/bin/agy.

Why you reach for it: it is a different harness from the Claude session you're in. That makes it valuable for two things you can't do well from inside Claude:

1. Cost/speed arbitrage — push mechanical or high-volume work onto a cheaper, faster model (Gemini 3.5 Flash) instead of spending premium tokens.
2. Genuinely independent review — a Gemini- or GPT-OSS-backed reviewer is a real second opinion, not the same model grading its own homework. This is the "different-harness QC" pattern: the author is Claude, the reviewer is Antigravity.

Before doing anything, confirm it's installed and current: agy --version (expect 1.0.x). If the command is missing, tell the user to install it — don't try to install it yourself.

Defaults — start here

When you just need to hand work to agy and the user hasn't specified details, this is the safe default shape. Adjust from here; don't reason it out from scratch each time.

cd <repo-or-worktree>                       # scope the workspace
agy -p "<goal + an explicit verification step>" \
  --model "Gemini 3.1 Pro (High)" \         # capable default; drop to Flash for grunt work
  --dangerously-skip-permissions \          # or --sandbox; a headless run hangs without one
  --print-timeout 20m                       # bump above the 5m default for anything non-trivial

Then pick deliberately: model by task difficulty (table below), timeout by expected runtime, permission flag by how much you trust the workspace, and — for review/handoff — tell agy in the prompt to write its result to a file you can poll.

Gotchas that will bite you

• A wrong --model string does not error — it silently runs the default model. Copy strings verbatim from agy models. A typo means you paid for the wrong tier and never knew.
• The default --print-timeout is 5m, and if it fires mid-run you lose all output. Size it to the task; a real refactor or full-repo review needs 15–20m+.
• Without --dangerously-skip-permissions or --sandbox, a -p run hangs waiting for interactive tool approval that never comes.
• "Independent" review on a Claude model isn't independent if you (the caller) are Claude. Route QC to Gemini or GPT-OSS. See the harness-diversity rule below.
• Some commands in blog posts don't exist in the installed CLI (e.g. agy run, agy inspect, -m, /context, config.toml). Worse, an unknown subcommand doesn't error — agy prints its usage banner and exits 0, so a bogus agy inspect looks like it worked while doing nothing. Trust agy --help / agy help over anything you half-remember.