Antigravity delegate

Antigravity Delegate

Claude = orchestrator. Antigravity CLI (agy) = the worker.

agy runs on the user's Google One / Antigravity quota — separate from Claude's token budget. So every unit of work pushed to agy is tokens Claude never spends. Delegate the doing (legwork and first drafts); keep the judgment (decisions, security, final review). Pull back only the small distilled result, never the raw intermediate bytes.

agy replaces the Gemini CLI (sunsets for Google One / AI Pro / Ultra on 2026-06-18). It exposes Gemini 3.x, Claude, and open-weight models, has web search + file edit + shell + async subagents, and authenticates via the system keyring. See references/agy-cli.md.

---

When to Apply

Two delegation buckets:

A. Legwork — high-volume, low-judgment; you only need the conclusion. B. Drafting — a capable worker can produce a first version that Claude then reviews/integrates.

Task	Delegate?	Bucket / note
web search → answer	✅	A — search noise stays in agy
download files / datasets	✅	A — bytes never touch Claude context
grep huge logs/codebases → the hit	✅	A
run benchmark / validator → PASS/FAIL	✅	A — tool spam stays out
summarize a giant file	✅	A
frontend/UI scaffold, component draft	✅	B — Gemini Flash is strong here; Claude reviews
boilerplate, config, codemod, repetitive edits	✅	B — draft in agy, Claude verifies
generate unit tests for existing code	✅	B — Claude checks they're meaningful
architecture / trade-off decision	❌	judgment — keep in Claude
security-sensitive code or review	❌	keep in Claude
shipping code with NO review	❌	always review a draft before it ships
tiny task (a few lines)	❌	delegation overhead not worth it

Rule of thumb: delegate when the cost is volume or the value is a reviewable draft. Keep it when the value is a final decision. A draft from agy is an input to Claude's judgment, never a substitute for it.

Load references/agy-cli.md before constructing any non-trivial agy invocation.

---

Model Selection

Match the model to the subtask (run agy models for the live list; quote the exact name, parens included). (Low|Medium|High) sets reasoning effort — lower = cheaper/faster.

Subtask	Model	Why
search / download / scan / validate / summarize	Gemini 3.5 Flash (Low)	cheapest, fastest, best agentic/tool-use
frontend/UI drafts, code-gen throughput, multimodal	Gemini 3.5 Flash (High)	strong at UI + grounded tasks; more effort
deep reasoning, ultra-long-context, hard analysis	Gemini 3.1 Pro (High)	reasoning + long-context recall
correctness-sensitive code draft, test gen	Claude Sonnet 4.6 (Thinking)	coding precision, careful edits
hardest reasoning / knowledge	Claude Opus 4.6 (Thinking)	top reasoning (most expensive of the set)
cheap open-weight fallback	GPT-OSS 120B (Medium)	when a flagship isn't needed

Default to Gemini 3.5 Flash (Low) — escalate only when the worker itself must reason or the draft quality must be high. Cheaper models first; spend effort only where it pays.

---

Process

1. Frame a closed task with a crisp, bounded deliverable. Tell agy exactly what to output (e.g. "output ONLY the version string", or "write the component to src/Foo.tsx and reply with only the file path"). For drafting tasks, state the constraints Claude cares about (framework, style, file location) up front.

2. Pick the mode (controls tool auto-approval):

   • search — web/research. Read-only tools (web search) work unattended.
   • read — scan local files/logs. Read-only tools (file read) work unattended.
   • write — downloads, builds, validators, or writing code/files (--dangerously-skip-permissions, scoped to --dir). For expected, reversible actions. --out FILE auto-selects write mode.

3. Pick the model from the matrix above.

4. Run via the helper:

   scripts/agy-run.sh "<task>" --mode search --model "Gemini 3.5 Flash (Low)"
   

   Prints agy's plain-text answer to stdout (plain text, not JSON — no extraction step).

5. Pull back only the distilled result. For large artifacts (generated code, downloaded data), have agy write to disk (--out FILE / a target path) and only read the slice Claude needs. Never paste raw search dumps, file bytes, or whole generated files into context blindly.

6. Review and decide in Claude. For legwork: sanity-check the answer. For drafts: review the produced code/file, fix what matters, integrate. The judgment is Claude's; only the doing was delegated.

---

Token-Saving Patterns

• Draft → review. Let agy produce the first version of a component / boilerplate / test file (on its quota); Claude reviews the diff, not a blank page. Big win on frontend scaffolds.
• File-out, read-the-slice. --out FILE keeps bulky output (data, long code) on disk; Claude reads only what it must reason about.
• Cheapest-capable model. Use Gemini 3.5 Flash (Low) for legwork; reserve Pro/Thinking models for genuinely hard subtasks.
• Batch closed tasks. One well-scoped agy call beats several chatty ones.

---

Output

• Default: the helper prints agy's plain-text answer to stdout — what enters Claude's context.
• --out FILE: agy's work lands on disk; the reply is a one-line summary; Claude reads the needed slice.

---

Error Handling

Exit code	Meaning	Action
0	success	use the answer
1	general / runtime failure (or empty response)	check stderr; retry once, then fall back to doing it in Claude
2	input error (bad prompt/args/mode)	fix the prompt/flags and rerun
other	passed through from agy	inspect stderr

• Empty response on a tool-needing task → re-run with --mode write (auto-approves tools).
• agy not installed → stop delegating, do it in Claude, tell the user to install: curl -fsSL https://antigravity.google/cli/install.sh | bash.
• Long task hitting --print-timeout (default 5m) → raise --timeout or split the task.
• Never silently swallow a failure — surface it, then decide retry vs. do-it-here.

---

Never Do

• Never delegate the final judgment: architecture decisions, security review, or shipping code without Claude reviewing the draft first.
• Never pipe agy's raw intermediate output (search dumps, file bytes, whole generated files) back into Claude's context unreviewed — defeats the token saving and the quality gate.
• Never use write / --dangerously-skip-permissions for destructive or irreversible actions, or outside a scoped dir.
• Never trust a delegated result blindly for anything that matters — verify the answer, review the draft.