🛰️ 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
/antigravity:migrate [--apply] [--include-repos]	move an existing Claude Code setup onto agy — skills, CLAUDE.md, memory, MCP, plugins, permissions; dry-run by default, --uninstall reverses it

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.

---

📦 Bringing your Claude Code setup across

/antigravity:migrate moves an existing Claude Code configuration onto agy. Dry-run by default; --apply backs up first and --uninstall --apply reverses it. Your ~/.claude is never written to.

/antigravity:migrate                             # see the plan
/antigravity:migrate --apply                     # global assets
/antigravity:migrate --apply --include-repos     # also AGENTS.md + per-repo memory

your Claude Code asset	becomes
~/.claude/skills/	read in place — a skills.json entry, not a copy, so one edit serves both tools
installed plugins	~/.gemini/config/plugins/ via the native importer, with its output repaired
CLAUDE.md	an AGENTS.md symlink beside it
auto-memory	always-on rules — global ones in a plugin, per-repo ones in <repo>/.agents/rules/
MCP servers (project + desktop app)	merged into ~/.gemini/config/mcp_config.json
trusted projects	trustedWorkspaces
permissions.allow	a proposal file — see below
session history	nothing. Antigravity stores conversations as protobuf blobs inside per-conversation SQLite files; there is no writer

Two things are deliberately not automatic. Permissions widen when translated — Claude's allow-list holds whole command lines, while agy's command() matches a prefix — so the result is written out for review and merged only with --apply-permissions. model / effortLevel / env are reported and never written, because no honest mapping exists.

Worth knowing if you would rather do it by hand: an Antigravity rule without trigger: always_on in its frontmatter is ignored with no error and no warning, workspace .agents/ is ignored entirely unless the session is bound to an agy project, and agy plugin import claude finds nothing on a current Claude Code because it only looks one directory deep. docs/MIGRATION.md has the full layout reference, the compatibility matrix, and how each of these was measured.

---

🗳️ 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. It is also the shape for people who live in a terminal.

gemini-studio-mcp is the same thesis on the other surface: Claude Desktop, for the colleagues who will never open one. An MCP server rather than a CLI delegation, and the verb flips from execute to ingest — Gemini reads the recording, the PDF corpus, the internal search index, and only the digest reaches Claude. The split is not cosmetic: you can hand a developer a --tier flag and an AGENTS.md, but a business user drags a PDF into a chat window, so the routing that is explicit here is automatic there, and the cost discipline that is a documented practice here is a number printed on every response there. They also fail differently — delegated writing can silently not happen and has to be checked against the filesystem; delegated reading can quietly summarise away the one paragraph that mattered and has to be checked against citations. Same author as this plugin.

quorum-review is the third 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.

---

🛠️ Direct script usage & tiers

# 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.)

💸 How to actually get the savings (cost discipline)

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).

🚧 Guardrails & known limits

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. <dir> is a placeholder — substitute a real path. Left as written it grants nothing on any agy version, and the write is soft-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 (--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.

📦 What's inside · local dev · tests

.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

---

🤝 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.