# 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 — and, since agy 1.1.28, any URL read — need --yolo (or a read_url(<target>) rule) headless
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.

The flash tiers moved to Gemini 3.8 Flash in 0.26.0 (3.7 in 0.24.0; 3.5 before that). 3.8, 3.7 and 3.6 carry identical list prices — $0.75 in / $3.75 out / $0.075 cached-in per 1M tokens — under promotional pricing that ends 2026-12-31, after which all three settle at $1.50 / $7.50 / $0.15 (3.5 is $1.50 / $9.00 / $0.15 throughout). Checked against two sources on 2026-09-03; prices.json carries both sets. No quality claim is made here — the reason to move is currency at an unchanged list price, and this repo has retracted a model comparison before for being measured on a build where --model was ignored. An identical per-token price is not an identical per-task cost: thinking bills as output, nothing here has measured how much of it 3.8 does, so read the AGY_USAGE line. One quirk was measured while checking this release: under --digest, a prompt that gives agy nothing to inspect (a bare "reply OK" ping) makes 3.8 High run a command to find something to report — 6 of 7 runs here, which headless without a grant is exit 15 (3.7 High 0 of 3, 3.8 Medium 1 of 6, 3.8 High without --digest 0 of 2). Given a real task — a file behind --dir, or code pasted into the prompt — 3.8 High answered 6 of 6. Give it a task, or drop --digest for a ping. If your plan does not serve 3.8 yet (agy 1.1.25's release note lists it for GEMINI_API_KEY sign-in; agy models also lists it on the GCP-project sign-in this was measured on, but newer models can lag on enterprise plans) you find out immediately, not silently: agy-doctor warns that the tier model is absent from agy models, and a delegation exits 14 naming the fix. Remap with the tier_flash / tier_flash_lo options to anything agy models lists — Gemini 3.7 Flash (High) and Gemini 3.6 Flash (High) cost exactly the same. (agy 1.1.5 switched agy models to slugs like gemini-3.8-flash-high; 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 — a grant over your whole machine, not over --dir. --sandbox does not contain it. 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. Use a throwaway checkout, or a permissions.allow rule instead of the flag.
• 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. Since 0.28.0 that line also names the model that ran and the tier it was picked from (empty for an explicit --model), plus agy's own duration_seconds / num_turns (1.2.x; 0 on older agy), so a usage log prices itself per tier. 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.

• Pipe hang and empty-output semantics moved upstream. agy 1.1.24 fixed the cause of the issue-#37 hang (its MCP children kept the caller's pipes open); the wrapper keeps routing agy's output through files, which costs nothing and still covers older builds. Since agy 1.1.18 a dropped agent stream exits non-zero instead of rc 0 + empty, so the wrapper's exit 3 now means agy genuinely returned nothing (from agy's changelog; not reproduced here).

• An expired --print-timeout is no longer a failure on agy's side (1.1.28). agy returns the partial reply with rc 0 and one stderr line ([agy] print timeout after 5s with turn in progress; returning partial output, measured on 1.2.0) and reports no usage for the turn. The wrapper prints that partial reply and still exits 12, so a truncated answer never passes as a finished one; --continue resumes the conversation.

• 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+ · hard error by 1.1.13 · soft again from 1.1.20, measured on 1.1.25: rc 0, empty output, the auto-denied notice on stderr). An ungranted write always leaves your workspace untouched; what changed is how the run admits it — a stderr notice from 1.1.3, a failed run on 1.1.13–1.1.19, the notice again since 1.1.20 (#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. <dir> is a placeholder — substitute a real path. Left as written it grants nothing on any agy version, and the write is denied with the rule sitting visibly in the file. A different mistake is the version-sensitive one: a command(...) rule that names no command (command(time), a comment-only entry, ()) matched every command before agy 1.1.11 and silently auto-approved anything the agent ran — broader than the --yolo it was chosen instead of. 1.1.11 makes that entry match nothing too. agy-doctor checks your entries and reports the consequence that actually applies.
  • --yolo — the wrapper's flag, sent to agy as --dangerously-skip-permissions (agy 1.1.25 rejects a literal --yolo) — auto-approves all tools, not just writes. Needed when no rule covers the target, and for web search / URL reads (agy 1.1.28 made fetching URLs ask first; the narrow rule is read_url(<target>)) / Vertex AI Search / terminal tools. Since agy 1.1.27 the wrapper names the refused tool from the envelope's denied_actions (measured on 1.2.0).

  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 both denial shapes — the soft one (agy 1.1.3+, and again from 1.1.20; re-measured on 1.1.25) and 1.1.13's hard error — 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 · agy-migrate
scripts/          agy-delegate · agy-job · agy-cost-compare · cloud-debug · agy-trace · agy-media · measure-session · doctor · agy-migrate
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