agy — Antigravity plugin for Claude Code

Read this in other languages

🇺🇸 English | 🇨🇳 简体中文 | 🇧🇷 Português

Use Google's Antigravity CLI (agy) from inside Claude Code: review code, delegate tasks, ask quick questions, research topics, and generate images — without leaving your editor.

This is a full architectural port of openai/codex-plugin-cc that swaps the Codex runtime for Antigravity's agy binary, keeping the same layered design — thin commands/*.md → a companion CLI script → a runtime library → per-workspace job/state persistence → text/JSON rendering — and adding commands that only make sense for Antigravity: image generation, a cheap one-shot question path, and web research.

What You Get

• /agy:review and /agy:adversarial-review — structured, JSON-schema-enforced code review of your working tree or a branch diff, runnable in the foreground or background
• /agy:delegate — hand a task to agy through a forwarding subagent; write-capable by default
• /agy:ask — the cheapest path: one question, one verbatim answer, no background job
• /agy:image — generate an image with agy's built-in generate_image tool, saved to an absolute path you choose
• /agy:research and /agy:deepresearch — single-pass or multi-hop web research via search_web + read_url_content
• /agy:status, /agy:result, /agy:cancel — inspect, fetch, or stop background jobs
• /agy:setup — check that agy is installed and authenticated, and toggle the optional stop-time review gate

Requirements

• Antigravity CLI (agy) installed and authenticated — either via OAuth (run agy once interactively) or ANTIGRAVITY_API_KEY
• Node.js 18.18 or later
• git

Install

Add the marketplace in Claude Code:

/plugin marketplace add Or4cu1o/antigravity-plugin-cc

Install the plugin:

/plugin install agy@agy-plugin-cc

Reload plugins:

/reload-plugins

Then run:

/agy:setup

/agy:setup tells you whether agy is installed and authenticated. If it's missing, it can offer to install it for you:

curl -fsSL https://antigravity.google/cli/install.sh | bash

If agy is installed but not authenticated, run it once interactively to complete OAuth:

!agy

or export ANTIGRAVITY_API_KEY in your shell.

After install, you should see the slash commands listed below and the agy:agy-delegate subagent in /agents.

One simple first run:

/agy:review --background
/agy:status
/agy:result

Usage

/agy:review

Runs a structured agy review against your current working tree, enforced by a JSON schema (verdict, summary, findings[], next_steps[]).

Use --base <ref> for a branch review, --scope auto|working-tree|branch to force a target, and --wait/--background for execution control. It is not steerable and does not take custom focus text — use /agy:adversarial-review for that.

/agy:review
/agy:review --base main
/agy:review --background

This command is read-only. It will not fix issues or apply patches — only present findings and stop.

/agy:adversarial-review

A steerable review that challenges the chosen implementation and design, not just surface-level defects: tradeoffs, hidden assumptions, and whether a different approach would have been safer or simpler.

It uses the same target selection as /agy:review, including --base <ref>, but also accepts extra focus text after the flags.

/agy:adversarial-review
/agy:adversarial-review --base main challenge whether this was the right caching and retry design
/agy:adversarial-review --background look for race conditions in the retry logic

Also read-only.

/agy:delegate

Hands a task to agy through the agy:agy-delegate forwarding subagent. Write-capable by default — there is no read-only mode for this command; use /agy:review or /agy:ask when you want read-only.

/agy:delegate investigate why the tests started failing
/agy:delegate fix the flaky integration test with the smallest safe patch
/agy:delegate --resume apply the top fix from the last run
/agy:delegate --model gemini-3.6-flash-high --effort high investigate the regression
/agy:delegate --background refactor the retry logic in src/queue.ts

You can also just ask for it in plain language — Claude routes substantial hand-offs to the agy:agy-delegate subagent automatically:

Ask agy to redesign the database connection pooling to be more resilient.

Notes:

• if you don't pass --model, agy uses its own default
• --effort accepts only low, medium, or high (unlike Codex's six levels)
• --resume continues the latest tracked agy conversation for this Claude session and repository; --fresh forces a new one

/agy:ask

The cheapest path through the plugin: one prompt, one verbatim response, no persisted job, always foreground.

/agy:ask explain the tradeoffs between optimistic and pessimistic locking here
/agy:ask --model gemini-3.6-flash-high --effort low what does this regex do?

/agy:image

Generates an image with agy's built-in generate_image tool and saves it to an absolute path.

/agy:image a minimalist dark-mode dashboard mockup, blue accent color
/agy:image --name hero --output ./docs/hero.png isometric illustration of a developer at a desk

--output accepts a relative or absolute path; relative paths resolve against the repository root. Default output is <name-or-agy-image>.png in the repository root.

/agy:research and /agy:deepresearch

Delegate web research to agy's search_web and read_url_content tools.

/agy:research is a single-pass investigation and defaults to asking whether to run in the background. /agy:deepresearch is a multi-hop investigation and defaults to running in the background without asking, since it typically takes much longer.

/agy:research what's the current state of WASM GC support across major runtimes?
/agy:deepresearch --model gemini-3.6-flash-high survey post-quantum signature schemes used in TLS

/agy:status

Shows running and recent agy jobs for the current repository, scoped to the current Claude session by default.

/agy:status
/agy:status task-abc123
/agy:status task-abc123 --wait --timeout-ms 60000

/agy:result

Shows the final stored output for a finished job, including the agy conversation ID so you can resume it directly with agy --conversation <id>.

/agy:result
/agy:result task-abc123

/agy:cancel

Cancels an active background job.

/agy:cancel
/agy:cancel task-abc123

/agy:setup

Checks whether agy is installed and authenticated, and can offer to install it. Also manages the optional stop-time review gate:

/agy:setup --enable-review-gate
/agy:setup --disable-review-gate

When enabled, a Stop hook runs a targeted agy review of the previous turn before Claude Code is allowed to end the session, blocking on unresolved findings.

Warning

The review gate can create a long-running Claude/agy loop and may burn through usage limits quickly. Only enable it when you plan to actively monitor the session.

Typical Flows

Review before shipping

/agy:review

Hand a problem to agy

/agy:delegate investigate why the build is failing in CI

Start something long-running

/agy:adversarial-review --background
/agy:deepresearch survey how competitors handle multi-region failover

Then check in with:

/agy:status
/agy:result

Architecture

commands/*.md   →  scripts/agy-companion.mjs  →  scripts/lib/agy.mjs  →  agy subprocess (--print)
(thin markdown)    (CLI dispatcher)               (runtime)              (json | stream-json)
                          ↓
                   lib/state.mjs + lib/tracked-jobs.mjs + lib/job-control.mjs (per-workspace jobs)
                          ↓
                   lib/render.mjs (JSON payload ⟷ rendered text)

Commands are intentionally thin: no flag parsing happens in the markdown, only execution-mode decisions (foreground vs. Claude Code's Bash(..., run_in_background: true)). Every subcommand supports --json for structured output and a rendered-text mode for direct display.

The agy contract, verified against the real binary

• --output-format json returns a single envelope: {conversation_id, status, response, duration_seconds, num_turns, usage}.
• --output-format stream-json emits NDJSON where every line is {"event": "init" | "step_update" | "result", <event>: {...payload}} — the payload is always nested under the matching key, never flattened onto the line. The terminal result event carries the same envelope shape as the non-streaming path, so the plugin reads the final response from there rather than accumulating agent_response text deltas.
• agy's run_command tool always executes inside a fixed scratch directory (~/.gemini/antigravity-cli/scratch), independent of the conversation's cwd and --add-dir. Every prompt this plugin sends carries the absolute repository root and an explicit instruction to cd there before running shell commands — without it, any task that touches the repo silently operates on the wrong directory. This is the single most load-bearing fix in the port.
• --effort only accepts low, medium, high (Codex has six levels); unsupported values are rejected with a clear error rather than silently coerced.
• Conversations resume via agy --conversation <id> (persisted per job) or agy --continue (the CLI's own bare last-conversation memory, which the plugin deliberately does not fall back to for --resume — falling back would silently cross Claude session boundaries).

Testing

Pure node:test, no framework, no dependencies:

npm test                                    # node --test tests/*.test.mjs
node --test tests/runtime.test.mjs          # one file

tests/fake-agy-fixture.mjs writes a fake agy binary into a temp PATH directory that emits the same JSON/NDJSON contract as the real CLI (verified against it directly — see tests/runtime.test.mjs for the workspace-context and session-isolation regression tests). No test ever calls the real agy.

FAQ

Do I need a separate Antigravity account for this plugin?

If you're already signed into agy on this machine, that authentication works immediately here too — the plugin uses your local agy CLI install and its cached auth state.

Does the plugin use a separate Antigravity runtime?

No. It delegates through your local agy binary, on the same machine, using your local authentication, repository checkout, and environment.

Can I keep using agy directly outside this plugin?

Yes. Delegated tasks and reviews can be resumed directly with agy --conversation <id> — the ID is shown by /agy:result and /agy:status.

Credits

This project is a derivative work built on two upstream projects — see THIRD_PARTY_NOTICES.md for full attribution:

• openai/codex-plugin-cc (Apache-2.0) — the layered architecture, job/state persistence design, and testing approach this project ports, with the Codex runtime replaced by agy.
• simplybychris/antigravity-plugin-cc (MIT) — a smaller, Bash-only plugin with the same goal. Several command ideas here (/agy:ask, /agy:delegate, /agy:review, /agy:image) and the visual design of this project's GitHub Pages site were inspired by that project's command surface and documentation.

License

MIT.