antigravity-for-claude-code
Run the Antigravity CLI (Gemini) as a collaborating AI inside Claude Code, with intelligent model routing across the SDLC.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/yuting0624/antigravity-for-claude-code with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/yuting0624/antigravity-for-claude-code'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/yuting0624-antigravity-for-claude-code)HTML
<a href="/listings/yuting0624-antigravity-for-claude-code"><img src="/api/listings/yuting0624-antigravity-for-claude-code/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](https://antigravity.google/docs/cli-using) (`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](https://github.com/yuting0624/antigravity-for-claude-code/issues/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**.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 17 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "antigravity-for-claude-code",
- "description": "Run the Antigravity CLI (Gemini) as a collaborating AI inside Claude Code, with intelligent model routing across the SDLC.",
- "owner": {
- "name": "linyuting"
- },
- "plugins": [
- {
- "name": "antigravity",
- "description": "Hybrid Claude Code + Antigravity (Gemini) workflow: Claude conducts requirements/architecture/the hard 20%/verification, and routes deterministic, high-volume work (scaffolding, tests, first-pass review, migrations, web/Vertex AI Search) to Antigravity. Lower token cost as a financial lever.",
- "source": "./",
- "category": "ai",
- "keywords": ["antigravity", "gemini", "multi-agent", "sdlc", "model-routing"]
- }
- ]
- }
README.md · README · 341 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- # 🛰️ 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.
- [](https://github.com/yuting0624/antigravity-for-claude-code/actions/workflows/ci.yml)
- [](LICENSE)
- 
- [](https://antigravity.google/docs/cli-using)
- </div>
- ---
- ## ⚡ 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`.
- - **Hand-off mode** — `/antigravity:handoff` gives agy a whole, test-covered task; Claude reads nothing and verifies only by running the tests. The one delegation shape that measured **cheaper than Claude Code alone** on implementation work (0.58× per passing task; 0.43× on large tasks — and a loss on small ones), at the price of a 3–4× longer wall-clock and code that needs the human review a first draft gets.
- - **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`](docs/AB-RESULTS.md).
- > **Note on cost figures:** numbers are **estimates** — token counts are approximated and rates live in [`prices.json`](prices.json). **Set your real Vertex rates there before quoting any figure.**
- **Hand-off mode, measured on real pull requests (2026-09, on `agy 1.2.2` only; #91).** Eight merged PRs from caddy,
- cli/cli, k6 and zoekt (52–2,242 lines), replayed with the PR's tests restored before
- scoring, Claude Opus 5 conducting, agy on Gemini 3.8 Flash, n = 2 per cell, blinded
- two-family review. Delegating file by file while Claude reads and specifies cost
- **1.33–1.68×** a solo run per passing task. Handing the **whole** task to agy and verifying
- only by running the tests (`agy-handoff`) cost **0.58×** (95% CI 0.39–0.96) at the
- pre-registered price deck — **0.43×** on large tasks, **1.20×** on small ones — with 16/16
- tests passed and the Claude side alone at 0.16×; the blinded Claude judge rated that code
- 0.6 of 5 below the solo run (dead code, duplicated helpers), about 0.2 below the human-merged
- PR. At the Gemini unit price this project was actually billed (2× the promotional rate) the
- overall saving disappears and large tasks keep 0.77×. Full protocol, per-run records and
- deviations: [PR #91](https://github.com/yuting0624/antigravity-for-claude-code/pull/91).
- ## 🚀 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](https://antigravity.google/docs/cli-using) (`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](https://github.com/yuting0624/antigravity-for-claude-code/issues/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
- <img src="docs/image.png" alt="The /antigravity slash commands in a Claude Code terminal session" width="720">
- *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\|flash-lo\|pro] <task>` | delegate a subtask to agy under cost discipline, then verify |
- | `/antigravity:handoff [--dir <repo>] [--tests <files>] <requirement>` | hand a **whole** test-covered task to agy; Claude reads nothing, the wrapper runs the tests, allows one fix-up, and reports — 0.58× a solo run per passing task on the PR-replay benchmark (small tasks: more) |
- | `/antigravity:review [--adversarial]` | independent cross-model review of the current diff; Claude reconciles |
- | `/antigravity:research [--tier flash\|flash-lo\|pro] [--timeout 15m] <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 (`:cancel` terminates the full job process tree and marks `state=cancelled`) |
- | `/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 |
- | `~/.claude/agents/` | nothing. A user subagent's `model:` names a Claude tier (`opus` / `sonnet` / `haiku`) and its `tools:` lists Claude tool names, so there is no honest mapping; subagents shipped *inside a plugin* come across with the plugin |
- | `~/.claude/CLAUDE.md`, `~/.claude/commands/`, `hooks` in `settings.json` | nothing — only the copies that ship inside a plugin are carried across |
- | 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`](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**](https://github.com/yuting0624/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**](https://github.com/yuting0624/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.
- ---
- <details>
- <summary><b>🛠️ Direct script usage & tiers</b></summary>
- ```bash
- # 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"
- # scoped read-only web / URL research (agy >= 1.4.10; synthesizes --settings request-review + read_url(*) without --yolo)
- scripts/agy-delegate.sh --tier flash --read-only --allow-url "Web-search <X>. Give URLs + dates."
- # write task: needs a grant — a permissions.allow write_file(<dir>) rule, --mode accept-edits (agy >= 1.5.7, workspace writes only), or --yolo (run on a branch)
- scripts/agy-delegate.sh --yolo --dir ./app "Implement X per SPEC.md"
- # reasoning effort override + structured JSON Schema output (agy >= 1.4.10 / 1.5.8)
- scripts/agy-delegate.sh --tier flash --effort xhigh --json-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "Summarize repo layout"
- # 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 (cancel terminates the full job process tree)
- scripts/agy-delegate.sh --tier pro --read-only "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 status "$ID"; scripts/agy-job.sh result "$ID" # or: scripts/agy-job.sh cancel "$ID"
- ```
- | tier | model | use for |
- |------|-------|---------|
- | `flash` (default) | Gemini 4 Hydrogen (High) | most bulk work (~2.5× faster agentic throughput) |
- | `flash-lo` (`lite`) | Gemini 4 Hydrogen (Low) | cheapest, low-latency tasks |
- | `pro` | Gemini 4 Carbon (High) | harder coding / reasoning / cross-checks |
- | `argon` · `flash-38` (aliases) | Gemini 4 Argon (High) · Gemini 3.8 Flash (High) | explicit Argon reasoning or promotional $0.75/$3.75 3.8 Flash |
- **agy is multi-model.** Tiers default to Gemini 4, but you can use any model `agy models` lists
- (Claude / GPT on plans that expose them): pass `--model "<exact name>"` (and optional `--effort low|medium|high|xhigh|max`), or set it persistently
- via plugin options — `default_model`, or per-tier `tier_flash` / `tier_flash_lo` / `tier_pro`
- (in `~/.claude/settings.json` under `pluginConfigs["antigravity@antigravity-for-claude-code"].options`
- or via 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 default tiers moved to the Gemini 4 family in 0.31.0 (measured manually on Linux with `agy 1.5.9` via Vertex AI ADC, `AGY_ADC_AUTH=true`):** `flash` / `flash-lo` (`lite`) use **Gemini 4 Hydrogen (High)** / **(Low)** ($1.50 in / $7.50 out / $0.075 cached-in per 1M tokens — standard non-promotional pricing with a 95% implicit prefix cache discount ≥ 4,096 tokens, plus `(XHigh)` via `--effort xhigh`), and `pro` uses **Gemini 4 Carbon (High)** ($2.00 in / $10.00 out / $0.10 cached-in introductory through **2026-11-30**, settling at $4.00 / $20.00 / $0.20 standard from **2026-12-01**; [`prices.json`](prices.json) carries both sets alongside `Gemini 3.8 Flash`'s $0.75 / $3.75 promotional rate through **2026-12-31**, accessible via `--tier flash-38`). When `tier_flash`, `tier_flash_lo`, or `tier_pro` is **unremapped** and your active plan does not expose the primary Gemini 4 model (for example Google AI Pro without Carbon/Hydrogen, Free-tier accounts, or Google Workspace accounts signed in via consumer `1. Google OAuth` instead of `2. Use a Google Cloud project` / `AGY_ADC_AUTH=true` — see [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md)), `agy-delegate` resolves an entitled fallback in **two layers**: first, it parses the `Available models:` list from `agy`'s error output to jump directly to the first entitled fallback in a single retry (`pro`: Carbon → Argon → 3.1 Pro → 3.1 Pro High/Low → Hydrogen → 3.8 Flash; `flash`: Hydrogen → 3.8 Flash → 3.7 Flash → 3.5 Flash; `flash-lo`: Hydrogen Low → 3.8 Flash Low → 3.5 Flash Lite → 3.1 Flash Lite); second, it caches the resolved model for 6 hours in `~/.cache/antigravity-claude/tier-models-v1.tsv` (keyed by `agy` version + auth fingerprint, and pre-seeded by `agy-doctor`) so subsequent calls hit the entitled model on attempt #1 with zero retry delay. Check `AGY_USAGE.model` on stderr for the model that actually ran. (Note: on `Gemini 3.8 Flash (High)` under `--digest`, a bare "reply OK" ping with nothing to inspect was measured to run a command 6 of 7 times — exit 15 headless without a grant; give it a real task or drop `--digest` for a ping. Both slugs and display names work with `--model`, and `doctor` matches either.)
- </details>
- <details>
- <summary><b>💸 How to actually get the savings (cost discipline)</b></summary>
- 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 — **using exact `AGY_USAGE` token counts (including additive `cache_read`) on `agy ≥ 1.1.8` and falling back to char-count estimates on older plain-text runs; verify `prices.json` first.**
- **Running a PoC in your org?** [`docs/POC-PLAYBOOK.md`](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).
- </details>
- <details>
- <summary><b>🚧 Guardrails & known limits</b></summary>
- > **Something broken?** See **[docs/TROUBLESHOOTING.md](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` up to 64 KB, or via a rewindable temp file `< "$PROMPTF"` without `-p` above 64 KB to avoid Linux `E2BIG`; measured on `agy 1.4.8` and `1.5.9` with `--output-format json`). **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` returns a partial reply (1.1.28+).** On agy 1.1.28–1.4.x, agy returns the partial reply with rc 0 and `[agy] print timeout after ...` on stderr; on agy 1.5.0+ (reported on 1.5.1 in [#115](https://github.com/yuting0624/antigravity-for-claude-code/issues/115), measured on 1.5.9), agy exits `3` with `finished_reason: "print_timeout"` in the JSON envelope and `AGY_ERROR` `"reason":"print_timeout"` on stderr (for both mid-turn and background-task wait timeouts). Either way, the wrapper prints any partial reply on stdout and exits `12` (`TIMEOUT`), so a truncated answer never passes as a finished one and never misreports as `AGY_FAILED`; `--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](https://github.com/yuting0624/antigravity-for-claude-code/issues/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](https://github.com/yuting0624/antigravity-for-claude-code/issues/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](https://github.com/yuting0624/antigravity-for-claude-code/issues/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.
- </details>
- <details>
- <summary><b>📦 What's inside · local dev · tests</b></summary>
- ```
- .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):
- ```bash
- 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
- bash tests/run-tests.sh
- ```
- </details>
- ---
- ## 🤝 Contributing
- Early-stage and MIT — issues, PRs, and ⭐ all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [`good first issue`](https://github.com/yuting0624/antigravity-for-claude-code/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 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](https://github.com/yuting0624/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](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.