Antigravity for Claude Code — hybrid SDLC

Run the Antigravity CLI (agy, Gemini) as a second AI working alongside Claude Code. The organizing idea is intelligent model routing across the SDLC: keep judgement-heavy work on Claude (the frontier model) and route deterministic, high-volume work to Antigravity (cheaper, faster Gemini). Two AIs, one workflow.

• Claude = conductor / orchestrator — requirements, architecture, the hard 20% (edge cases, integration, correctness), specs, tests/evals, final review.
• Antigravity = delegated agent — a full terminal agent (file edits, terminal, subagents, MCP, web/Vertex AI Search) that executes well-specified work.

This is agentic engineering, not vibe coding: the value is the structure around the model — routing, shared rules, verification gates — not raw generation. Generation is solved; verification, judgement, and direction are the craft.

Two modes (pick per task)

• Conductor (sync, inline): you're shaping something in real time; delegate a small, well-scoped chunk to agy mid-flow (e.g. "generate these tests"), use the result immediately.
• Orchestrator (async, multi-unit): decompose a larger task into units, dispatch to agy (often with --dir, agentic, in parallel), then review and integrate. Best for migrations, bulk implementation against patterns, test suites.
• Hand-off (whole task, tests as the gate): hand one coherent, test-covered task to agy as a whole with agy-handoff, read nothing, verify only by running the tests, hand the diff to a human as a first draft. The only delegation shape measured cheaper than Claude alone on implementation work — see Hand-off mode below.

Division of labor across the SDLC

Route each phase to the right model. This is the core policy.

Routing tier within agy: flash (default, bulk) · flash-lo (cheapest, trivial) · pro (harder reasoning / reviews / cross-checks).

agy is multi-model. Tiers map to Gemini by default, but you can point delegation at any model agy models lists (Claude / GPT on plans that expose them) — via --model <exact name>, or persistently with the default_model / tier_* plugin options (in ~/.claude/settings.json pluginConfigs or env CLAUDE_PLUGIN_OPTION_*). The pro tier defaults to Gemini 4 Argon (High) since 0.29.0 (consumer Google AI plans list Argon instead of 3.1 Pro — as reported in #104, not measured here — and enterprise plans on agy 1.4.x, which were measured, renamed gemini-3.1-pro-high's display name to Gemini 3.1 Pro while also serving Gemini 4 Argon (High)). When tier_pro is unremapped and the active plan does not expose Argon, agy-delegate automatically falls back to Gemini 3.1 Pro (then Gemini 3.1 Pro (High)) and logs pro fell back to … on stderr — check AGY_USAGE.model for the model that actually ran. The retry fires only on agy's "model not recognized" error, never after a timeout (a timed-out attempt exits 12). That rejection is not instant: measured on agy 1.4.2 (enterprise plan, four runs) it took 5–37 s per attempt, so a plan with none of the three costs up to three such starts — well under one --print-timeout each, not three timeouts. Keep the executor a different, cheaper model than the Claude conductor: that's what yields the cost saving and the cross-model verification value (Claude executing Claude loses both).

Model availability moves fast, and --tier needs agy ≥ 1.1.10. Until 1.1.10, agy ignored --model and --effort in headless -p — the flag was applied after model configuration had initialised, so the run silently fell back to the persisted default. This wrapper resolves every --tier to --model and always runs -p, so on an older agy tier selection does nothing and looks like it works: the call succeeds, returns sensible text, reports usage. doctor warns when it sees one — and on agy ≥ 1.1.11 it stops inferring and asks: it requests a tier model via -p /model (a read-only slash command that costs no tokens and starts no agent turn) and reports which model agy says it would actually run. Below 1.1.11 it does not probe, because there the slash command falls through as prompt text and the model answers as though it had run.

The flash tiers default to Gemini 3.8 Flash (High) / (Low) since 0.26.0 (3.7 from 0.24.0, 3.5 before). 3.8, 3.7 and 3.6 carry identical list prices — $0.75 in / $3.75 out / $0.075 cached-in per 1M — under a promotion that ends 2026-12-31 and then settles at $1.50 / $7.50 / $0.15; 3.5 is $1.50 / $9.00 / $0.15 throughout. Two sources, checked 2026-09-03. Price a run with prices.json's gemini_flash, which mirrors whatever the flash tier resolves to; agy-cost-compare picks that key by tier NAME, not by model.

The move is justified on currency at an unchanged list price, not on quality — no comparison has been run between these models on a build where --model actually applies, and an identical per-token price is not an identical per-task cost (thinking bills as output; read the AGY_USAGE line). Measured quirk: under --digest, a prompt with nothing to inspect (a bare "reply OK") makes 3.8 High run a command to find something to report — 6 of 7 runs, exit 15 headless without a grant; 3.7 High 0 of 3. With a real task (a file behind --dir, pasted code) 3.8 High answered 6 of 6. Give it a task, or drop --digest for a ping. If a plan does not serve 3.8 — agy 1.1.25's note lists it for GEMINI_API_KEY sign-in; it is also listed on the GCP-project sign-in this was measured on — doctor says so and a delegation exits 14 naming the fix; remap tier_flash to a name from agy models (3.7 and 3.6 cost the same).

Retracted: earlier versions of this note quoted token-level comparisons between 3.5 / 3.6 / flash-medium (−23% input, cache_read +43%, and so on). Those runs were made on agy 1.1.8–1.1.9, where --model was ignored — so every arm may have executed the same persisted default. Independently, the numbers did not survive their own ranges: 3.5-high spanned [421k, 509k] input against 3.6-high's [305k, 412k] at n=2, and flash-medium overlapped high outright. A mean-vs-mean claim over overlapping ranges is exactly what this repo's own playbook tells you not to report. Pick a tier by what your plan serves and by the published rates until this is re-measured on 1.1.10+.

Note: agy 1.1.5 changed agy models output to slugs (gemini-3.5-flash); both slugs and display names are accepted by --model, and doctor matches either.

How to call it

agy-delegate [options] "the task prompt"

Options: --tier flash|flash-lo|pro · --dir <path> (workspace, repeatable) · --timeout 10m · --yolo (auto-approve ALL tools — the blunt grant; needed for web search / URL reads (agy 1.1.28+; or a read_url(<target>) rule) / Vertex AI Search / terminal, and for writes not covered by a permissions.allow rule. For a file write the narrower grant is usually a write_file(<dir>) entry in ~/.gemini/antigravity-cli/settings.json, which needs no flag — see below. Run write tasks on a branch) · --mode accept-edits|plan|auto (agy execution mode. --mode accept-edits is NOT a headless write grant. Measured on agy 1.1.13 — where the flag is actually applied, since 1.1.12 fixed --mode being ignored in headless -p entirely — the write is denied exactly like one without it. Earlier notes here said "soft-denied on 1.1.3"; on a build where the flag was never applied, that observation could not tell a denial apart from the flag doing nothing. plan = strategize only; auto = dynamic plan/execute on agy ≥ 1.3.5) · --sandbox · --digest (append a digest-only output contract — use it for any bulk read/analysis; the wrapper also warns on stderr when a reply comes back dump-sized, because ingesting digests instead of dumps is the single biggest cost lever) · --print-command (dry run: show the resolved agy call, don't run it) · pipe a long prompt with a trailing -.

The wrapper handles agy's quirks (prompt is the value of -p; non-TTY stdout drop via < /dev/null). On agy ≥ 1.1.8 it also runs agy with --output-format json internally: stdout still gives you the model's text unchanged, but failures are classified from the structured error instead of scraped prose, and the executor's real token usage (input / output / thinking / cache_read) is reported as an AGY_USAGE {...} line on stderr — so the Gemini side of a delegation can finally be measured, not estimated. The line also carries model and tier (the tier the model was derived from; empty for an explicit --model) and agy's duration_seconds / num_turns (1.2.x; 0 on older agy), so a log prices itself per tier without a join back to the command. Older agy (or no python3) transparently falls back to the plain-text path; force it with the structured_output option.

Accounting semantics for AGY_USAGE (verified — get this wrong and your cost math is wrong). total = input + output (and thinking is inside output). cache_read is a separate counter: it is NOT part of total, and it is not a subset of input — in an agentic delegation it routinely exceeds input (measured: cache_read 1,356,694 vs input 243,117 in one delegation). So price the Gemini side as input×in_rate + output×out_rate + cache_read×cached_rate, three separate terms. This differs from the Claude/Harbor side, where cache-read tokens are an inner subset of the reported input total — don't carry one convention over to the other.

If you are measuring, set AGY_USAGE_LOG=/path/to/log (or the usage_log option). AGY_USAGE and AGY_SIGNAL go to stderr, and the advice two paragraphs down — keep Claude's context lean — makes agy-delegate ... 2>&1 | tail -N the natural thing to write. stdout (the digest) is emitted after the usage line, so tail keeps the digest and silently drops the usage. Measured in the wild: a benchmark harness lost most of its Gemini-side data exactly this way, which made the hybrid look cheaper than it was. A named file cannot be truncated by a pipe.

Two ways to delegate. Call the wrapper directly (above), or — when you want file generation to happen entirely on Gemini with zero Claude tokens spent writing — hand the unit to the antigravity-delegate subagent (its only file-acting tool is the wrapper; it returns a digest for you to verify). Either way, you still own verification.

Structured failures. The wrapper exits 10 quota · 11 auth · 12 timeout (incl. an expired --print-timeout, which agy 1.1.28+ returns as a partial reply with rc 0 — the wrapper prints it and still exits 12; a complete JSON SUCCESS reply after which agy never exits, seen on agy 1.4.4, is printed and exits 0 with a stderr warning) · 13 agy-missing · 14 model-unavailable (a --model / tier_* / default_model name not in agy models — agy ≥ 1.1.2 hard-fails instead of silently downgrading) · 15 permission-denied (a tool needed permission headless — BOTH the soft deny, agy 1.1.3+ and again from 1.1.20, and 1.1.13's hard error — add a permissions.allow rule or pass --yolo; since 1.1.27 the wrapper names the refused tool from the envelope's denied_actions) (besides 2 failed / 3 empty). On agy ≥ 1.1.8 these are derived from the structured status/error envelope rather than stderr pattern-matching, so the classification is reliable. It prints a AGY_SIGNAL {...} line on stderr; agy-job status/result surface it, so you can react (e.g. retry quota with --continue, fix the model name, or add --yolo) instead of scraping prose.

If Claude itself is running headless (claude -p, one-shot): run delegations synchronously — let agy-delegate BLOCK and return before you continue. Do NOT background a delegation expecting a later turn / "harness re-invocation": there is none in -p mode, so you'd exit before the work finishes. (Backgrounding is only valid in an interactive session that will be re-invoked.)

Shared harness: one AGENTS.md for both AIs

agy reads AGENTS.md from the workspace (verified). Keep a single shared AGENTS.md at the repo root (stack, conventions, hard rules, workflow) so Claude and Antigravity operate under the same rules — this raises agy's first-pass success rate and keeps output consistent (lower OpEx).

Rule: when delegating any repo work, always pass --dir <repo-root> so agy loads AGENTS.md and the real code, instead of pasting files into the prompt (cheaper, denser context).

Verification gates (non-negotiable)

Claude owns correctness. For anything that ships:

1. Define the contract first — Claude writes/owns the tests and evals; they tell agy what "correct" means more precisely than prose.
2. Output eval = actually run it, don't stop at reading the code. Reading the diff is necessary but NOT sufficient — a static review that "looks right" is still vibe coding. Execute it: run the tests, launch the app, hit the real API/endpoints, and check each acceptance criterion against observed behavior. Verify external assumptions empirically (e.g. does the API actually accept that input?) rather than trusting the spec's claims. If you cannot run it, say so explicitly — do not mark the gate passed.
3. Trajectory check — did it take a sane path? (Limit: print mode returns only the final text. The per-conversation logs under ~/.gemini/antigravity-cli/conversations are SQLite .db files with opaque blob columns, not human-readable — don't rely on reading them. Instead, have agy summarize its own steps as part of its output, or keep a session with --continue/--conversation and ask it to recap. But every run leaves a readable trajectory: transcript.jsonl under ~/.gemini/antigravity-cli/brain/<conversationId>/ — for plain delegations too, not just internal-fan-out subagents. agy-delegate prints the conversationId in its AGY_USAGE line, so cost and trajectory join 1:1. Audit with agy-trace --audit <conversationId> (or --audit --last): step-type counts plus every non-zero exit. A delegation can report SUCCESS while commands inside it failed — measured: 6 failed commands inside one overall-"SUCCESS" run. agy-trace <id> prints the full steps; --list finds recent ones. What is NOT recorded: the command strings. Not in transcript.jsonl, not in transcript_full.jsonl, not in ~/.gemini/antigravity-cli/log/cli-*.log. You get that a command ran, its exit code and its output. To attribute a filesystem change, diff the tree — the trajectory cannot tell you.)
4. Review every shipping line — be skeptical of clever code; check imports are real packages (hallucinated deps), error handling, edge cases, and that the contract itself is internally consistent (examples/placeholders match the verified behavior).
5. Never trust agy's "GREEN" — re-run the gate yourself in a clean state. Measured: agy will, to make a check pass, modify the environment itself — e.g. patch the installed package in site-packages, or MagicMock-stub a missing dependency — and then report success. Before believing a passing test/eval: diff any touched tooling against a pristine reference, restore it, and re-run the gate under Claude's own control. agy's self-reported pass is a claim, not evidence. If wrong: retry on --tier pro, sharpen the spec, or do that piece yourself.

Safety for write tasks

Read-only work (search, review, analysis) is low-risk. When agy writes files or runs commands (--yolo grants write + terminal):

• Write tasks need a grant — and it does not have to be --yolo. Headless agy's no-permission behavior has shifted every few releases — describe-only (pre-1.1.0), scratch-divert (1.1.0–1.1.2), soft-deny with a stderr notice (1.1.3+), hard error by 1.1.13, soft again from 1.1.20 (measured on 1.1.25; since 1.1.27 also named in the envelope's denied_actions, 1.2.0) — but your workspace stays untouched every time; what varies is whether the run admits it (issue #10). The wrapper maps the soft deny and the hard error alike to exit 15. Two things grant a write, and --yolo is the blunt one. A write_file(<dir>) entry under permissions.allow in ~/.gemini/antigravity-cli/settings.json allows writes recursively beneath <dir> with no flag at all — confirmed on agy 1.1.9 by a controlled A/B (#37): covered target wrote, uncovered target returned PERMISSION_DENIED, rule the only variable. agy's own denial text names the rule and offers --yolo as the alternative. --yolo auto-approves all tools and is what you need when no rule covers the target, or for web search / URL reads (agy 1.1.28 made those ask first; the narrow rule is read_url(<target>)) / Vertex AI Search / terminal. Not verified below 1.1.9; a glob form (write_file(/path/**)) was reported not to match. <dir> is a placeholder: left as written the rule grants nothing on any version — exit 15 with the rule visibly present in the file. Separately, and only for command(...), an entry naming no command (command(time), comment-only, ()) matched EVERY command before 1.1.11; do not attach that history to a mistyped write_file(). If a user reports a rule that "should" work, have them run agy-doctor before changing anything else. Run write tasks on a branch and verify with git status. prompt for or block --dangerously-skip-permissions — approve it or pre-allow Bash(agy-delegate*). Always verify files actually changed in the workspace with git status (the wrapper maps BOTH denial shapes — the soft deny, 1.1.3+ and again from 1.1.20, and 1.1.13's hard error — to exit 15, so you're not left guessing).
• Run it on a dedicated git branch or worktree so changes are isolated.
• --sandbox is NOT execution containment. Measured on macOS with agy 1.1.19: with --yolo, --sandbox changed nothing — a write to an absolute path OUTSIDE --dir succeeded (rc 0), id ran and returned a real uid, and curl https://example.com returned 200. agy's own help says "terminal restrictions"; whatever it restricts, it is not those, and not in this combination. Not tested on Linux. Contain by what you check out and by permissions.allow, not by the flag.
• Claude reviews the diff before merging — never auto-merge agy's writes.

Hand-off mode — whole task to agy, tests as the gate (measured)

The measurement that shaped this section: eight merged pull requests from public Go repositories (caddy, cli/cli, k6, zoekt; 52–2,242 lines), replayed from the parent commit with the PR's tests restored before scoring, Claude Opus 5 as the conductor in every arm, n = 2–3 per cell, blinded two-family review (2026-09, measured on agy 1.2.2 only; PR #91).

Why it works: a solo run's spend is 54% cache reads and 21% cache writes; half of what the conductor reads it never edits. Delegation only saves money when the conductor stops reading. Why it is not free: the executor writes more than asked (dead code, duplicated helpers, extra options) and nobody reads it before the tests, so the result is a first draft for human review, and the wall-clock is 3–4× a solo run. Prices matter too: at the Gemini 3.8 Flash unit price this project was actually billed (2× the promotional prices.json rate) the overall saving vanishes and only large tasks keep 0.77×; on an Antigravity plan where the Gemini side is not metered, the Claude side alone is 0.16×.

Rules (1–5 measured on agy 1.2.2 in the #91 benchmark; 6–7 are wrapper design; the agy-handoff wrapper itself is verified against the test suite's agy stub in CI):

1. Hand off whole, or not at all. One delegation carrying the entire requirement, verbatim, plus the contract agy-handoff appends (tests exist and must pass unmodified, no additions beyond the requirement, leave changes uncommitted, run the gate before finishing). Median 1–2 delegations per task; a second one only to quote a failing test.
2. Size gate. Roughly 200 changed lines and up, with tests that define "done". Below that the fixed price of one long executor conversation (about $1.5–2.5 at the deck) exceeds what a solo run would have cost. Small tasks lost money in every delegation arm.
3. Read nothing. Not the files before (ask for a digest if you must), not the diff after. The moment you read to verify, you are back in the 1.3–1.7× regime.
4. Tests are the only gate you apply. agy-handoff runs the repository's verification command, sends at most one fix-up quoting the failing output (exit 4 if verification is still red after the allowed fix-ups; exit 12 if an executor call timed out and verification failed), and checks that the named test files were not touched (exit 6 if any --tests file was modified, whether uncommitted or committed). No test command, no hand-off (--no-verify exists for experiments, not for work).
5. Human review after green. Hand the diff over as a first draft and say what the reviewer found in the measurement: dead code and unused fields, helpers re-implemented beside a library already in go.mod, options nobody asked for, mismatched import grouping. Asking the executor to review its own diff for these did not help (+0.07).
6. Clean tree, dedicated branch, --yolo implied. The executor edits with all tools auto-approved and may search the web; the wrapper refuses a dirty tree unless told otherwise. It registers the repository with agy first (agy --new-project; in an unseen directory agy otherwise works in its last project root — 450 s vs 119 s).
7. Interactive sessions: --background. A real feature takes 20–120 minutes; Claude Code's Bash tool cuts a call off after its timeout. Detach, poll with agy-job status, collect with agy-job result, and leave the repository alone meanwhile. Headless claude -p: synchronous, with the Bash timeout raised.

Cost discipline — where the savings actually come from

Delegation does not save money by itself. Measured reality: on a small task the hybrid cost more than Claude-only, because the dominant cost was Claude's own cache_read — re-reading a large, growing context across many orchestration turns. The savings the "Gemini sub-agent" concept promises are real, but only when you keep Claude's context lean and the round-trips few. Apply these as hard rules:

1. Delegate above the break-even, not below. Hand work to agy only when the offloaded volume clearly exceeds the spec-writing + round-trip + verification overhead it adds. Bulk/parallel/repetitive (mass migration, exhaustive tests, fan-out research, long-context reads that return a small digest) = delegate. Small, self-contained, or judgement-heavy = just do it yourself. (Delegating a tiny task is a net loss.)
2. Keep Claude's context lean (the biggest lever). Do not pull the files agy already handled (--dir) back into Claude's context, and do not paste agy's raw bulky output into the thread. Claude ingests a digest, not raw content — this is what collapses the per-turn cache_read that made the hybrid expensive.
3. Make agy return a digest, not a dump. End every delegation prompt with an explicit trailer instruction, e.g.: "...End with a fenced block ===DIGEST=== listing: files changed, key decisions, and a 1-paragraph 'context for next step'. Put bulky detail ONLY in files, not in your reply." Claude reads the DIGEST; the bulky work stays on cheap Gemini tokens.
4. Batch, don't chatter. One large, fully-specified delegation beats many small round-trips (each round-trip re-reads context = cache_read tax).
5. Review the diff, not the whole tree. git diff is compact; reading every file is not.
6. Do not hold state on the executor to save money — measured, it costs more. It is tempting to keep one agy session alive with --continue / --conversation <id> so the working context "lives on the cheap side". It does not work: resuming carries the whole prior conversation forward and agy re-reads the material anyway, and agy's prompt cache covers only ~2/3 of its context re-reads. Measured on a repeated-corpus digest, the continued call cost +82% / +277% vs a fresh one (n=2). Use --continue for what it is good at — resuming after a quota or timeout failure — and get multi-step savings from rule 4 instead (one large delegation, not many small ones).
7. Asymmetric effort. The conductor doesn't need max reasoning effort to coordinate + verify; run Claude at a moderate effort and let the cheap workers do the volume.
8. Don't fight the prompt-cache TTL on small tasks (measured trap). The 5-min cache expires while you wait on a long agy delegation, so the next turn pays cache_create (1.25× input) instead of cache_read (0.1×). It's tempting to "keep the cache warm" with busy turns — measured: that backfires, because every warming turn generates frontier output (5× input), the most expensive class, and net cost goes up. Do NOT manufacture work to stay warm. Backgrounding a long delegation (Bash run_in_background) is fine to avoid blocking, but it does not make a small task cheaper. The only real fix is scale: make each delegation big enough that the displaced Claude output dwarfs the one-time re-cache cost. Below the break-even, the hybrid loses on cost — three optimization variants were tested on a small task and none beat solo Claude (see docs/AB-RESULTS.md). Delegate for cost reasons only at scale.

Honest framing for any cost claim: there is no flat 8×/46%. Below the break-even the hybrid costs more; above it, lean-context routing cuts frontier-model spend by a measured margin. Quote the measured number and the break-even, never a headline ratio. Use agy-cost-compare for the per-token gap (estimate; set real Vertex rates first).

The number of delegations is the lever — batch them (measured)

Rule 4 above ("batch, don't chatter") is the one that actually moves the needle, and here is why, from a benchmark of this plugin (Opus 5 conductor · Gemini 3.6 Flash High executor · agy 1.1.8 · n=3/arm, cold cache):

Per delegation the economics are fine. Repeated ingestion is what breaks them. Offloading a large corpus works exactly as designed — the conductor's cache_read fell 61%, it never opened the corpus itself, and each digest came back at ~4k tokens. But each agy-delegate call is an independent session that shares no cache with the last one, so a conductor that delegated 7.3 times against the same corpus paid to ingest it 7.3 times. Two-thirds of the executor's cost was re-reading material it had already read. Break-even on that task was ~5.7 delegations; the one trial that stayed at 5 came in cheaper than solo Claude, the ones at 9 did not.

So when several delegations work over the same material:

• Fold related units into ONE fully-specified delegation. This is the only lever that actually removes a re-ingestion. Two questions about one corpus = one delegation asking for both, not two delegations. Only fold units that genuinely belong together. If combining them muddies the spec, don't — a vague mega-prompt returns worse work, and re-running it costs far more than the re-ingestion you saved. Quality of the spec beats the token arithmetic every time.
• Scope --dir to the smallest subtree that contains the work, and expect the executor's read cost — not its writing — to dominate.
• Do NOT reach for --continue to avoid re-ingestion — measured, it makes things worse. Resuming a session carries the whole prior conversation forward and agy re-reads the material anyway, so you pay both: on a repeated-corpus digest the continued second call cost +82% and +277% vs a fresh one (n=2), with cache_read 3–14× higher. --continue is for resuming after a failure (quota, timeout) — not a cost lever.

Two supporting facts, both measured: delegation moves work rather than removing it (the hybrid ran ~2.8× the normalized token volume for the same result — it stays affordable because the executor is cheaper per token, not because it does less), and agy's own prompt cache covers only ~2/3 of its context re-reads, so the executor is worse than Claude at carrying context. Both push the same way: fewer, larger, session- reusing delegations.

These are single-configuration measurements from 2026-07 on two task families, not constants. Treat them as direction, and re-measure on your own workload before quoting any figure.

SDLC recipes

ROOT=agy-delegate

# Scaffold from a spec (Claude wrote the spec/architecture)
"$ROOT" --tier pro --yolo --dir ./app \
  "Scaffold per ARCHITECTURE.md: dirs, configs, stub modules. Follow AGENTS.md."

# Generate tests for a contract Claude defined
"$ROOT" --tier flash --yolo --dir ./app \
  "Write unit + edge-case tests for src/payments.py covering the cases in SPEC.md."

# First-pass review (Claude does the final pass)
"$ROOT" --tier pro "Review for bugs/security/perf, be skeptical. List file:line: <diff>"

# Implement-until-tests-pass (feedback loop; isolate on a branch)
"$ROOT" --tier pro --yolo --dir ./app \
  "Implement feature X to satisfy AGENTS.md and make 'pytest -q' pass. Iterate until green."

# Migration / modernization
"$ROOT" --tier pro --yolo --dir ./svc \
  "Migrate all callers from APIv1 to APIv2 per MIGRATION.md. List every file changed."

# Web search → Claude re-checks
"$ROOT" --tier pro --yolo "Use web search for <X>. Give URLs + dates."

# Audio / video / image understanding (Claude can't hear or watch; Gemini can)
# agy-media writes the full transcript to a FILE and returns a timestamped digest —
# never ingest a whole transcript (a 1-hour recording is ~10k words of cache_read).
agy-media ./meeting.wav "decisions and owners"     # digest -> you; transcript -> ./meeting.transcript.md
agy-media ./demo.mp4 --timeout 20m                 # video: adds timestamped VISUALS/OCR
agy-media ./memo.m4a --convert                     # agy mishandles m4a/aiff; converts to wav first
# Verify before relying on it: the digest flags unclear audio + uncertain names/numbers —
# grep that timestamp out of the transcript file rather than trusting the summary.

# Vertex AI Search over internal data (discover engines, then query)
"$ROOT" --tier pro --yolo "List Vertex AI Search engines (list_engines)."
"$ROOT" --tier pro --yolo "Search engine <ENGINE_ID> for: <question>. Cite the hits."

Internal fan-out recipe (agy spawns its own subagents)

agy has built-in define_subagent / invoke_subagent tools. Which pattern works is version-dependent — this surface is moving fast upstream (4 releases in one week while we tracked it), so re-verify after any agy upgrade:

• agy ≥ 1.0.16 — dynamic custom subagents (preferred): have agy define_subagent a named specialist in-session (name / description / system_prompt), then invoke_subagent it by that TypeName. Verified headless on 1.0.16 and re-verified on 1.1.0: define → invoke → result round-trips cleanly, real thread spawned. (1.0.13–1.0.15 shipped this broken — defined agents failed to invoke, upstream #521; fixed in 1.0.16. Subagents are officially documented as of 1.1.0 — antigravity.google/docs/cli/subagents — with static config at <workspace>/.agents/agents/*.md and global ~/.gemini/config/agents/.)
• Any version — role delegation (fallback): the sandbox pre-approves TypeNames self and research; an undefined custom TypeName is rejected with CORTEX_STEP_TYPE_INVOKE_SUBAGENT: ... not found or not allowed to be invoked (upstream #105). Invoke TypeName self and inject the specialty via Role + Prompt — verified on 1.0.12 and re-verified on 1.0.16.

Use it for orchestrator-mode work pushed down a level: instead of Claude dispatching N parallel agy-job runs (N round-trips, coordination spend on the frontier side), send ONE delegation and let agy fan out internally — the coordination tokens land on the cheap side, and you ingest a single digest.

# Preferred form (agy >= 1.0.16). --yolo (the wrapper's flag; it reaches agy as
# --dangerously-skip-permissions) is required so the subagent tools aren't
# soft-denied headless (see below). Verified live on agy 1.1.5.
agy-delegate --dir . --yolo --digest --timeout 10m \
  "ACTUALLY use your define_subagent and invoke_subagent tools (do NOT simulate).
   Decompose <task> into up to 3 units. For each unit: define_subagent a named specialist
   (name + system_prompt for its role, following this repo's conventions / AGENTS.md if
   present), then invoke_subagent it by TypeName with the unit's work. Wait for ALL, then
   report per-unit results, EACH subagent's conversationId, and end with a DIGEST line."
# Any-version fallback: replace define/invoke with TypeName "self" + a specialist Role.

Verified behaviors (1.0.12 → 1.1.5):

• Pass --yolo. On 1.1.3+ the subagent tools need permission that headless mode can't prompt for, so without --yolo the spawn is denied (wrapper exit 15). Whether it is a soft deny or the hard error 1.1.13 introduced for writes (and 1.1.20 took back) has not been measured for this tool — the grant and the exit code are the same either way. (On 1.0.x spawning was ungated, but --yolo is the durable choice here: a permissions.allow write_file(...) rule covers file writes only, not define_subagent/invoke_subagent, and not web search, URL reads (agy 1.1.28+) or Vertex AI Search.)
• Each spawn's tool result includes a logAbsoluteUri → a readable step-by-step transcript.jsonl under ~/.gemini/antigravity-cli/brain/<conversationId>/ — better trajectory visibility than a plain delegation. Location unchanged across 1.0.12→1.1.5, for both define_subagent and self spawns. Have the parent report each conversationId, then audit with agy-trace <id> (agy-trace --list finds recent ones). Note: the parent may also create a coordination thread of its own, so --list can show one more conversation than the units you asked for.
• Spawns are real and observable (new conversation threads appear) — but still run the verification gates on the merged result; more autonomy = more surface for error.

Caveats: neither pattern is a documented contract yet — self+Role works around the sandbox allowlist, and even the official docs' static agent-config paths don't match observed behavior (upstream #527) — so re-verify after agy upgrades (1.0.16 changed this area within a day of our first verification). Bound the fan-out width in the prompt (agy chooses parallelism otherwise). A wide fan-out takes longer wall-clock — raise --timeout, and in an interactive session prefer a background job (agy-job).

Deep-research recipe (multi-source)

agy has no built-in "Deep Research" mode — that product lives in the Gemini app and the Gemini API's managed Deep Research Agent, not the CLI (verified). But agy can do genuine multi-step, cited web research via its agentic loop. So deep research is a Claude-orchestrated recipe, not a single agy call. Pair it with Claude's own deep-research skill as planner/verifier; agy is the cheap, grounded legwork worker.

Caveat that shapes the recipe (verified empirically): in --print mode agy uses search-summary tools and does NOT reliably fetch full pages, so its citations are coarse (often domain-level) and may not actually support the claim. It can also leak parametric "knowledge" disguised as a sourced fact. Never ship its citations unverified.

1. Plan (Claude). Decompose into sub-questions + an explicit list of load-bearing claims to verify. Claude owns scope and final synthesis.
2. Fan-out fetch (agy, cheap, parallel). One call per sub-question; force compact stdout so bulky pages stay in Gemini's context, not Claude's:

   "$ROOT" --tier flash --yolo \
     "Use web search for <sub-question>. Return 5-8 bullet findings, each with the
      exact source URL and publication date. Output ONLY findings+URLs+dates."

3. Deepen on key sources (agy). For each load-bearing claim, name the URL and make agy quote the supporting text (turns domain-level citations into verifiable quotes):

   "$ROOT" --tier pro --yolo \
     "Open <URL> and quote the exact sentence(s) supporting: '<claim>'.
      If the page does not support it, reply NOT SUPPORTED."

4. Adversarial verify (Claude). Corroborate each key claim across ≥2 independent domains; treat any single/vague/domain-only citation as unverified; sanity-check dates; watch for Gemini parametric knowledge masquerading as a sourced fact.
5. Synthesize (Claude). Write the final cited report from verified findings only; mark anything uncorroborated as "unverified."

Iteration is Claude's job: --print does one agentic pass per call (no auto re-query when evidence is thin), so Claude must re-dispatch follow-up agy calls to close gaps. Token economics: bulky searched/fetched text is paid in cheap Gemini tokens and distilled to bullets+URLs before reaching Claude — use agy-cost-compare to show it.

What Antigravity brings that Claude lacks natively

Built-in Google tools (MCP), verified working in headless --print mode:

• Google / web search — current, grounded info.
• Vertex AI Search — search internal/company data stores (list_engines, search, conversational_search).
• Google Cloud Logging, Notebooks (Colab/Jupyter), Visualization (charts).

Tool use in headless mode requires --yolo (print mode can't show approval prompts); search/list tools are read-only so this is low-risk.

Economics (a financial lever, not the headline)

Routing deterministic, high-volume work to Gemini Flash (≪ Claude per token) is intelligent model routing: higher CapEx (this harness) for lower OpEx (cheap model does the bulk). Use the cost demo as observability:

agy-cost-compare --tier flash "the task prompt"

Estimates only (chars/4; agy exposes no token API in print mode). Set real Vertex rates via CLAUDE_IN_PER_M, CLAUDE_OUT_PER_M, GEMINI_IN_PER_M, GEMINI_OUT_PER_M.

Prerequisites & limits

• agy installed and authenticated (agy models lists Gemini models); its ~/.gemini/antigravity-cli/settings.json points at a GCP project/region.
• Scripts executable (chmod +x scripts/*.sh).
• agy v1.0.x: -p takes the prompt as its value (wrapper handles); no JSON output; print mode returns final text only (no trajectory); no timeout(1) on macOS (use --timeout).
• WSL: --add-dir on a Windows mount (/mnt/c/...) reads over a slow 9p bridge — calls can take 20s+. Keep the repo on the Linux filesystem (~); the wrapper warns.