Driving agy headless

A focused recipe for one specific job: route work to your Antigravity (agy) Pro account instead of burning your main Claude/codex quota. agy is a real, paid engine — use it. But it behaves differently from claude -p / codex exec, and most wasted agy quota comes from driving it the wrong way. This page is the canonical how-to so you don't re-learn it (and re-burn it) every session.

TL;DR — agy is global, single-account, not burnable. That does not mean "can't be used." It means: clikae can't auto-reroute it across tanks like burn does for claude/codex. You drive it headless on the active account with clikae agy <tank> -- -p, and switch accounts interactively between batches.

The one mental-model fact

agy's Google login is a single global Keychain entry, not a per-shell env var. So:

There is no clikae env agy and no per-shell routing — clikae env agy fails on purpose and points you here.
clikae agy <tank> swaps ~/.gemini (and its login) machine-wide — one agy account is active across all terminals at once. It's exclusive, not parallel.
clikae burn can't include agy in a reserve walk (nothing to reroute to on the same machine). agy relay is sequential, by hand: run a batch, switch tank, run the next. See agy-gemini-shared-quota notes for why same-account agy↔gemini is a fake relay (same quota bucket).

The canonical headless invocation

# Switch agy to a tank (machine-wide), then run it headless on that account.
# Prompt goes through a FILE — never cram a paragraph into a shell-quoted -p '…'.
clikae agy <tank> -- \
  --print-timeout 900s \
  --add-dir /abs/path/to/repo  `# only if the task must read/write files outside cwd` \
  -p "$(cat /tmp/agy_prompt.txt)"

That's it. The rules below are the difference between this returning real work and returning a blank.

Rules that keep agy from firing a blank (hard-won)

Headless agy is -p (print mode), never -i. agy -i needs a real TTY (it's a bubbletea TUI) and dies headless with could not open TTY. Any agent-driven or background call uses -p.
Pass the prompt via a file, not nested quotes. -p "$(cat /tmp/foo.txt)". Nested sh -c '… -p "…"' quoting silently eats the prompt and agy answers the wrong thing. One layer, file-fed.
Don't collect big output from stdout — let agy write a file. agy -p's stdout return is unreliable for large/structured output: the process stays alive at 0% CPU and buffers everything, emitting nothing. For anything big, tell agy to write the result to a file itself (agentic), then read that file. Where it lands: ~/.gemini/antigravity-cli/brain/<session-id>/*.md — -p's stdout is often just a one-line pointer to it.
Give a dead task, hard boundaries, and a long timeout. agy's interactive strength — free exploration — is a liability headless: it will wander (e.g. go investigate a git diff) and burn the whole timeout writing nothing. Fence the prompt explicitly ("don't check git, don't investigate, only do X and write Y") and give --print-timeout 900s (default ~5 min is too short for real work).
macOS has no timeout. --print-timeout doesn't always kill cleanly. For unattended jobs, wrap the call in an outer hard kill (e.g. Python subprocess.run(..., timeout=N)) as a backstop.
pkill -9 -f "agy -p" before switching tanks. clikae agy <tank> refuses to switch while an agy process is live (swapping ~/.gemini under it would corrupt the session). Kill stale/hung print jobs first.
Reading files outside cwd needs --add-dir <abs path> (pre-authorise), or feed pure text via stdin (cat file | agy -p "…") so no tool/permission gate is hit. A bare agy -p that tries to read an un-authorised path hangs forever waiting on a permission prompt that has no TTY to answer it.
--dangerously-skip-permissions is for a human, not an agent. When clikae is being driven by another AI (e.g. Claude Code), that AI's safety classifier blocks an agy call carrying --dangerously-skip-permissions — even with a Bash(agy:*) allow-rule. Plain agy -p (no skip flag) passes. If a task genuinely needs skip-permissions, the human runs that line (e.g. !-prefixed); don't expect an agent to self-authorise it.
Rotate tanks across batches to spread the weekly cap. One global account = sequential execution; alternating tanks (clikae agy 8 / clikae agy c / …) spreads usage across accounts. Net throughput is round-robin, not parallel.

What agy is genuinely good at headless

One-shot text generation — translation, transcreation, summaries, copy. Verified: it reliably produces single-shot output for well-scoped text tasks. (When asked to review zh-TW for Taiwanese voice, attach a Mainland→Taiwan term rubric — agy is Gemini underneath and will otherwise drift; treat it as a grader fed an explicit rubric, not a native ear.)
Live-web QA — agy has a read_url_content tool and really browses (fetches URLs, follows links, reads HTML). Good for buyer-journey / i18n / polish sweeps, one report file per lens. Smoke-test once (ask it to echo a page's real <h1>) to confirm it isn't guessing. Plain curl is more reliable for a bare liveness check — don't spend agy quota on "is the site up?".
Big file-writing jobs offloaded from your main quota — a whole translation dictionary, written to a file (rule 3), on the agy bucket, untouched by your Claude budget. This is the cost-aware-routing payoff.
A cheap breadth leg in clikae conduct — conduct --leg agy/<tank> fans a read-only audit/analysis prompt to agy alongside claude/codex legs, then hands you every leg's output to judge. agy is cheap and fast, so it's a good extra perspective for best-of-N. Caveat: the agy leg runs on the currently active agy tank only (a leg naming another tank is reported, not run — clikae can't switch agy in parallel). Its dry state is read from cli.log, not stdout.

⚠️ agy's review suggestions need triage. It will confidently recommend things that violate already-decided product calls. Never auto-apply an agy review's fixes — the orchestrator or a human filters them.

❓ Unverified (treat with care): one observation suggests agy -p may not run a fully autonomous multi-step file-editing loop the way claude -p / codex exec do — it may answer single-shot or defer to an async build and return. Single-shot text output is confirmed; the agentic edit-and-verify loop is not. If you plan to use agy as a burn-style code-editing worker, validate it with a controlled task first. See agy-gemini-shared-quota for the running ground-truth.

Driving agy (Antigravity) headless via clikae

The one mental-model fact

The canonical headless invocation

Rules that keep agy from firing a blank (hard-won)

What agy is genuinely good at headless

See also