# one-shot delegation (plain text on stdout)
scripts/agy-delegate.sh --tier flash "Summarize this changelog in 3 bullets: ..."

# give Antigravity a workspace for multi-file agentic work
scripts/agy-delegate.sh --tier pro --dir ./src "List every TODO with file:line"

# bulk read -> digest-only reply (the biggest cost lever; wrapper warns on dump-sized replies)
scripts/agy-delegate.sh --digest --dir . "Map the auth flow end to end"

# write task: needs a grant — a permissions.allow write_file(<dir>) rule, or --yolo (run on a branch)
scripts/agy-delegate.sh --yolo --dir ./app "Implement X per SPEC.md"

# live web / Google search (tools need --yolo in headless mode)
scripts/agy-delegate.sh --tier pro --yolo "Web-search <X>. Give URLs + dates."

# Vertex AI Search over internal data
scripts/agy-delegate.sh --tier pro --yolo "List Vertex AI Search engines (list_engines)."

# cross-model review / stdin / background job
scripts/agy-delegate.sh --tier pro "Review for bugs, be skeptical: <paste>"
cat big-prompt.txt | scripts/agy-delegate.sh -
ID=$(scripts/agy-job.sh start --tier pro --dir . "big task"); scripts/agy-job.sh result "$ID"

agy is multi-model. Tiers default to Gemini, but you can use any model agy models lists (Claude / GPT on plans that expose them): pass --model "<exact name>", or set it persistently via plugin options — default_model, or per-tier tier_flash / tier_flash_lo / tier_pro (env CLAUDE_PLUGIN_OPTION_*). Keep the executor a different, cheaper model than the Claude conductor — that's what gives both the cost saving and the cross-model verification.

Verified through agy 1.1.5. A newer Gemini 3.6 Flash now shows up in agy models and works — the flash default stays on Gemini 3.5 Flash (High) for broad plan availability (newer models can lag on enterprise Vertex); remap tier_flash to Gemini 3.6 Flash (High) when your plan serves it. (agy 1.1.5 switched agy models to slugs like gemini-3.5-flash; both slugs and display names work with --model, and doctor matches either.)

Delegation doesn't save money by itself — these do (also in the skill):

1. Delegate above the break-even — bulk/parallel/repetitive work, not tiny tasks.
2. Keep Claude's context lean — don't re-read what agy already handled; take a digest, not raw output. (Biggest lever — it collapses cache_read.) Enforced in code: --digest appends a digest-only output contract, and the wrapper warns when a reply comes back dump-sized (tune via the digest_warn_chars plugin option).
3. Batch — one big delegation beats many round-trips.
4. Review the diff, not the whole tree.

scripts/measure-session.py <session-id> prints the COST-WEIGHTED + est. USD breakdown for a session (Claude side; Gemini side priced separately). scripts/agy-cost-compare.sh shows the per-token gap for a task — estimates from char-count, so verify prices.json first.

Running a PoC in your org? docs/POC-PLAYBOOK.md is the step-by-step method — quality gate first, baseline, one lever at a time, break-even reporting, and org-level rollout/enforcement (incl. Windows/WSL requirements).

Something broken? See docs/TROUBLESHOOTING.md — symptom-first fixes for Windows/WSL, writes that silently don't happen, quota/auth/timeout codes, and updating.

Guardrails

• Always verify agy's output (it can be wrong, and may even alter its environment to make a check pass — re-run gates yourself in a clean state).
• --yolo auto-approves every tool call — use with --sandbox or in a throwaway dir.
• Write tasks: run on a dedicated branch/worktree, review the diff before merging.

Known limits (agy v1.0.x)

• -p/--print takes the prompt as its value and must come last — the wrapper handles this.

• --print drops stdout on a non-TTY unless stdin is detached (handled via < /dev/null). Structured output arrived in agy 1.1.8 (--output-format json): the wrapper now uses it internally on ≥1.1.8 to classify failures from the structured error and to report the executor's real token usage (incl. cache_read) as an AGY_USAGE line on stderr — stdout is unchanged. Older agy falls back to plain text (toggle with the structured_output option). If you're measuring, set AGY_USAGE_LOG=/path (or the usage_log option): stderr is easily lost — 2>&1 | tail -N, the natural way to keep Claude's context lean, keeps the digest and drops the usage line.

• The executor's trajectory is auditable. Every agy run writes a step-by-step transcript.jsonl, and the conversationId in AGY_USAGE joins it to the cost 1:1. agy-trace --audit <id> (or --audit --last) shows step-type counts and every non-zero exit — a delegation can report SUCCESS while commands inside it failed. The command strings are recorded nowhere, so to attribute a filesystem change you must diff the tree.

• Two write grants, and the narrow one is not --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 1.1.3+), and in every version an ungranted write leaves your workspace untouched while the run still "succeeds" (#10). Two things grant it:

  • permissions.allow in ~/.gemini/antigravity-cli/settings.json — a write_file(<dir>) entry allows writes recursively beneath <dir> and needs no flag. This is the narrower grant and usually the right one.
  • --yolo (--dangerously-skip-permissions) — auto-approves all tools, not just writes. Needed when no rule covers the target, and for web / Vertex AI Search / terminal tools.

  Confirmed on agy 1.1.9 by a controlled A/B (#37): a covered target wrote with no flag; an uncovered one came back PERMISSION_DENIED with the rule as the only variable. agy's own denial text names the rule and offers --yolo as the alternative. Not verified on other versions, and a glob form (write_file(/path/**)) was reported not to match. Either way: run write tasks on a branch and verify with git status; the wrapper maps a soft-deny to exit 15.

• Native Windows (no ConPTY): headless agy -p / agy models can hard-hang with a 0-byte log when stdio is redirected (issue #6). The wrapper wraps agy in a wall-clock timeout/gtimeout guard so it returns a structured TIMEOUT (exit 12) instead of hanging; doctor reports the likely hang instead of a misleading "not authenticated". Without timeout on PATH there's no safety net — use WSL/macOS/Linux for headless delegation.

• WSL: running agy with --add-dir on a Windows mount (/mnt/c/...) is very slow — agy reads the workspace over a 9p bridge, so even trivial calls can take 20s+. Keep the repo on the WSL Linux filesystem (~). The wrapper and doctor warn about this.

.claude-plugin/   plugin (+ userConfig: default_tier, timeout, coding_policy) + marketplace manifests
skills/antigravity/SKILL.md   WHEN + HOW Claude collaborates with agy
agents/           antigravity-delegate subagent (file work runs on Gemini, not Claude)
commands/         slash commands (delegate, review, research, media, cloud-run-debug, setup, status, result, cancel)
hooks/            SessionStart: agy health check + auto-inject the cost-aware policy
bin/              PATH shims (bare names): agy-delegate · agy-job · agy-cost-compare · agy-doctor · cloud-debug · agy-trace · agy-media · measure-session
scripts/          agy-delegate · agy-job · agy-cost-compare · cloud-debug · agy-trace · agy-media · measure-session · doctor
docs/             AB-RESULTS (measured A/B) · POC-PLAYBOOK · TROUBLESHOOTING · DEMO-KIT
prices.json       Vertex rate config (verify before quoting)

Local development (hack on the plugin — loads live files, $CLAUDE_PLUGIN_ROOT resolves):

git clone https://github.com/yuting0624/antigravity-for-claude-code ~/antigravity-for-claude-code
claude --plugin-dir ~/antigravity-for-claude-code

Tests (no dependencies; stubs agy):

bash tests/run-tests.sh