Antigravity Agents

Antigravity CLI Sub-Agents

Google Antigravity CLI (agy) is an autonomous terminal coding agent (Gemini and other models) that can read a repo, edit files, and run commands. This skill uses its non-interactive print mode to run delegated jobs: you write a self-contained task prompt, launch agy -p in the background, keep doing your own work, then collect and verify the result.

Treat an agy job like a contractor you briefed over email: it only knows what's in the prompt and the directory you point it at, and its work is unverified until you check it.

Resolving the binary

After install, agy is normally on your PATH. If a tool-spawned shell can't find it (some shells don't inherit a freshly updated PATH), fall back to the full path:

• Windows: %LOCALAPPDATA%\agy\bin\agy.exe (in Bash-style shells: "$LOCALAPPDATA/agy/bin/agy.exe")
• macOS / Linux: check which agy

Critical: always close stdin. agy blocks forever (0% CPU, no output, even in print mode) when stdin is an open pipe, which is exactly what non-interactive tool shells give it. Launch jobs with </dev/null appended (POSIX shells), or from PowerShell via cmd /c '... < NUL'. A "stalled" job with an empty log almost always means stdin was left open — kill it and relaunch with stdin closed.

Preflight (once per session)

Before the first job of a session, verify auth with a cheap probe:

agy -p "Reply with exactly: OK" --print-timeout 60s </dev/null

• Replies OK → authenticated, proceed.
• Prints a sign-in URL or errors about credentials → stop and tell the user to run agy once in their own terminal to complete the Google sign-in (it's a browser OAuth flow you cannot do for them). Don't retry until they confirm.
• Hangs with no output → you forgot </dev/null.

Conflict rule — the one thing that must not go wrong

An agy job and your own edits must never touch the same working tree at the same time. Decide the isolation level before launching:

For write jobs, snapshot first (git status --porcelain, commit or stash anything precious) so the sub-agent's changes are cleanly diffable — and recoverable if it goes sideways.

Launching a job

Run from the target repo's root (working directory is the workspace). Background it and redirect output to a log file so you can keep working:

cd <repo-root> && agy -p "$(cat <<'EOF'
<self-contained task prompt>
EOF
)" --print-timeout 10m --sandbox </dev/null > <tmp>/agy-<jobname>.log 2>&1

Run anything longer than ~1 minute in the background and read the log file when it exits.

Timing calibration (measured in testing): a trivial probe returns in ~10s; a full-repo review on Flash (High) took ~13 minutes and printed nothing until done — print mode buffers nearly all output to the end, so an empty log mid-run is normal, not a stall. Tell the user the expected window when you launch ("5–15 min, silent until done") so quiet doesn't read as stuck. Genuine-stall signature: log frozen AND near-zero CPU delta over ~10s — that means a missing flag, not a slow model.

Prefer fan-out over monoliths. One big multi-question job maximizes wall-clock and progress blindness. For anything with separable dimensions (review: correctness + performance + config-drift; audit: security + deps + dead code), launch 2–4 narrow parallel jobs instead — each finishes faster, results arrive incrementally, and you do the cross-cutting synthesis yourself, which you must do anyway during verification.

Flags that matter:

• --dangerously-skip-permissions — required for every print-mode job that uses tools, including read-only ones. agy's default permission mode (request-review) pauses on the first terminal command or file operation waiting for a human approval that never comes in print mode — the job silently freezes (process alive, log frozen, CPU flat). For read-only jobs pair it with --sandbox; for write jobs use it only inside an isolated worktree or a repo you're not touching.
• --sandbox — terminal restrictions; add to all read-only jobs as the safety layer alongside skipped permissions.
• --print-timeout — default is 5m; raise it (10m, 20m) for big jobs or they get cut off mid-work.
• --model "<name>" — recommended default is Gemini 3.5 Flash (Medium) for most jobs and Gemini 3.5 Flash (High) for meatier review/analysis: fast and strong for delegated work, and heavier "thinking" models usually aren't worth the extra latency here. Run agy models to see current options and swap in whatever fits your preference.
• --add-dir <path> — grant access to extra directories (e.g. a shared docs folder) without changing the working directory.