🛰️ 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

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-