🛰️ Antigravity for Claude Code

Run the Antigravity CLI (Gemini) as a collaborating sub-agent, right inside Claude Code. Claude conducts the judgement; Gemini does the heavy lifting — intelligent model routing across the SDLC.

---

⚡ Quick look

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

---

💡 Why

	Claude (conductor)	Gemini / agy (executor)
Owns	requirements · architecture · the hard 20% · verification · review	scaffold · implementation · test generation · search
Strength	judgement	cheap, fast throughput

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.
• Hears audio, watches video — /antigravity:media delegates the perception to Gemini (natively multimodal, no local ffmpeg/Whisper stack): you get a timestamped digest while the full transcript is written to a file, so a 1-hour recording never lands in Claude's context.
• 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:

	Claude solo @high	solo @max	hybrid
frontier cost (COST-WEIGHTED)	2.62M	5.34M	1.91M
quality (adk eval)	✅ 3/3	✅ 3/3	✅ 3/3

→ −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.

command	what it does
/antigravity:setup	health check — agy installed + authenticated, scripts ready
/antigravity:delegate [--tier flash|pro] <task>	delegate a subtask to agy under cost discipline, then verify
/antigravity:review [--adversarial]	independent cross-model review of the current diff; Claude reconciles
/antigravity:research <topic>	Claude-orchestrated deep research — agy does grounded web legwork, Claude verifies citations across ≥2 sources
/antigravity:media <file> [focus] [--convert]	understand audio / video / images — agy transcribes + analyzes, returns a timestamped digest; full transcript goes to a file, not your context
/antigravity:cloud-run-debug [--service <s>] [--region <r>] [--project <id>] [--since 1h] [--apply]	diagnose a failing Cloud Run service — agy digests the error logs, Claude infers the root cause + fix; read-only by default (--apply writes to a branch)
/antigravity:status [id] · :result <id> · :cancel <id>	manage background delegation jobs

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.

---

🗳️ The same two models, arranged differently

This plugin is one shape of Claude and Gemini working together: conductor and executor — judgement on one side, throughput on the other, one workflow.

quorum-review is the other shape: the two as peers. Both read the same pull request independently, neither sees the other's output, and where they agree independently that is the result — only the disagreements are worth a second opinion. Both run on one Google Cloud credential, so no vendor API keys live in the repository. Same author as this plugin.

This repo is its client zero. It runs on every pull request opened here, alongside a Claude review — including the ones that change this plugin. Keeping the habit of not quoting numbers we haven't measured, here is what that has actually been worth:

• On a fixture holding three known bugs it found two, with no false positives, and reached the correct root cause on one that the single-model review took two rounds to get right.
• Reviewing this repo's own CI, both of its models independently caught a fork-guard hole in the review workflow itself — one that would have put an outside contributor's code on the runner next to live credentials.
• It has also produced a confident false positive that both models agreed on — the code disproving it lived outside the checkout either model could read.

That last one is the useful lesson, and it cuts against the obvious pitch: two independent scans insure you against one model's blind spot. They do not insure you against a gap in what you handed both of them.

---

# 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"

tier	model	use for
flash (default)	Gemini 3.5 Flash (High)	most bulk work
flash-lo	Gemini 3.5 Flash (Low)	cheapest, trivial tasks
pro	Gemini 3.1 Pro (High)	harder reasoning / cross-checks

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 with the rule as the only variable. agy's own denial text names the rule and offers as the alternative. Not verified on other versions, and a glob form () was reported to match. Either way: run write tasks on a branch and verify with ; the wrapper maps a soft-deny to exit .

.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

---

🤝 Contributing

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

Automated review: PRs get two reviews in CI on top of the usual tests/shellcheck — a Claude review carrying this repo's own contracts, and quorum-review — see the section above.

From a fork: quorum doesn't run at all. The Claude review runs only once a maintainer with write access applies the claude-review label — the label alone isn't authorisation, since triage collaborators can apply labels too — and it re-runs on every later push, so an approved review can't go stale behind new commits. Your code never reaches the runner at all — the reviewer sees it as a diff (gh pr diff), with this repository's base checkout for context. Nothing of yours is fetched or executed.

---

⚠️ 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.