⚡ Quick look

Claude stays the conductor; the bulk, token-heavy read ran on cheaper Gemini, and Claude verified the result.

💡 Why

you → Claude Code (conduct: design / verify / review)
         └── agy → Gemini (execute: implement / test / search)

Generation is solved; verification, judgement, and direction are the craft.

✨ What it does

• Routes work across the SDLC — Claude keeps the judgement calls; Antigravity handles scaffolding, test generation, first-pass review, and migrations under a shared AGENTS.md.
• Adds tools Claude lacks natively — live Google/web search, Vertex AI Search over your internal data, deep research, Cloud Logging. Claude reviews and re-checks the results.
• Cross-model verification — an independent, different-model opinion on your code.
• Background jobs — fire a long delegation, keep working, collect later.
• Internal fan-out — one delegation, and agy spawns its own subagents on the cheap side (dynamic define_subagent on agy ≥ 1.0.16; TypeName "self" + Role on any version); each leaves a readable trajectory you audit with agy-trace.
• Built-in cost discipline — measured, not guessed (see below).
• Drops in with the discipline on — a SessionStart hook injects the cost-aware
  routing policy automatically (toggle in plugin settings), and the antigravity-delegate
  subagent does file writing on Gemini, so Claude spends no tokens generating file contents.
• No slash command required — the delegate subagent is picked up proactively for bulk
  work, and a prompt-level nudge flags bulk-looking requests as delegation candidates.
  Both are advisory: the break-even judgment stays with Claude (full auto-routing is a
  measured net loss below the break-even), and the nudge is toggleable (delegation_nudge).

📊 Measured results

On a large ADK multi-agent build (+ adk eval), same task / same model, 3 ways:

→ −27% vs solo@high, −64% vs solo@max, at equal quality — and the cheap Gemini work isn't even counted. Savings scale with task size; tiny one-off tasks are cheaper to just run on Claude. Full A/B: docs/AB-RESULTS.md.

Note on cost figures: numbers are estimates — token counts are approximated and rates live in prices.json. Set your real Vertex rates there before quoting any figure.

🚀 Install

In Claude Code:

/plugin marketplace add yuting0624/antigravity-for-claude-code
/plugin install antigravity@antigravity-for-claude-code
/antigravity:setup        # verifies agy is installed + authenticated

Prerequisites: the Antigravity CLI (agy) installed & authenticated (agy models lists Gemini models), and Claude Code. For the same-bill cost benefit, run Claude Code on Vertex too.

Platform support: macOS, Linux, and WSL are the supported targets for headless delegation. Native Windows (Git Bash/MSYS) is not recommended — agy -p can hang with a 0-byte log when run without a real console (ConPTY); see issue #6. The wrapper now bounds this with a wall-clock guard (GNU timeout/gtimeout, returning a clean TIMEOUT instead of hanging), and doctor distinguishes a hang from an auth failure — but for reliable headless use, run from WSL/macOS/Linux.

🧩 Slash commands

The plugin's commands show up natively in Claude Code's / menu.

Background jobs are for interactive sessions (fire-and-collect). In headless claude -p (one-shot), delegate synchronously — there's no later turn to collect a result.

# 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: auto-apply FILE edits without granting terminal/tools (agy >= 1.1.0)
scripts/agy-delegate.sh --mode accept-edits --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.

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.

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.
• No --output-format json (plain text); --print drops stdout on a non-TTY unless stdin is detached (handled via < /dev/null).
• Writes need write permission: without it, headless agy describes the edits or (agy ≥ 1.1.0, review-first default) writes them to its own scratch dir — your workspace stays untouched while agy reports success (issue #10). Prefer --mode accept-edits (agy ≥ 1.1.0; file edits only, no terminal/tool grant); use --yolo when the task also needs tools (web / Vertex AI Search). Run write tasks on a branch and verify files actually changed. Long write tasks can exceed the ~2-min sync Bash limit → use a background job.
• 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, cloud-run-debug, setup, status, result, cancel)
hooks/            SessionStart: agy health check + auto-inject the cost-aware policy
scripts/          agy-delegate · agy-job · agy-cost-compare · cloud-debug · agy-trace · measure-session · doctor
docs/             AB-RESULTS (measured A/B) · 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

🤝 Contributing

Early-stage and MIT — issues, PRs, and ⭐ all welcome. See CONTRIBUTING.md and the good first issue list.

⚠️ Disclaimer

Community project. Not affiliated with, endorsed by, or supported by Google or Anthropic. "Antigravity", "Gemini", "Claude", and "Claude Code" are trademarks of their respective owners. This plugin orchestrates the third-party agy CLI; you are responsible for your own API/cloud costs, credentials, and data-sharing choices. MIT licensed — see LICENSE.