agy-companion

Use Google's Antigravity CLI (agy) from inside Claude Code for code reviews or to delegate tasks — the same idea as Anthropic's codex plugin, but driving agy instead of Codex.

Created and maintained by John Hill (@unlikelyzero).

What You Get

• /agy:review for a code review of your current work
• /agy:adversarial-review for a steerable challenge review
• /agy:rescue, /agy:status, /agy:result, and /agy:cancel to delegate work and manage background jobs
• An optional stop-time review gate (/agy:setup --enable-review-gate)

Requirements

• The Antigravity CLI (agy) installed and on PATH, signed in with a Google account. agy has no headless/API-key auth path (see below).
• Node.js 18.18 or later.

Install

See docs/INSTALL.md for the full walkthrough. Short version:

/plugin marketplace add unlikelyzero/agy-companion
/plugin install agy@agy-companion
/reload-plugins
/agy:setup

/agy:setup tells you whether the agy binary is on PATH and whether it's signed in, using a free print-mode check that spends no quota — see Differences from codex-plugin-cc.

One simple first run:

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

Usage

/agy:review

Runs an agy code review on your current work.

Use --base <ref> for branch review. It also supports --wait and --background. It is not steerable and does not take custom focus text. Use /agy:adversarial-review when you want to challenge a specific decision or risk area.

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

This command is read-only, and structurally so: it runs against a disposable, .git-free copy of your working tree in a scratch directory (any AGENTS.md/CLAUDE.md/etc. instruction files stripped out of that copy first), not your actual checkout, so a write it makes lands in throwaway space instead of your repo. When run in the background you can use /agy:status to check on progress and /agy:cancel to cancel it.

/agy:adversarial-review

Runs a steerable review that questions the chosen implementation and design, the same way as codex-plugin-cc's /codex:adversarial-review.

/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 and question the chosen approach

This command is read-only, in the same structural sense as /agy:review above (a disposable snapshot, not your checkout). It does not fix code.

/agy:rescue

Hands a task to agy through the agy-rescue subagent.

/agy:rescue investigate why the tests started failing
/agy:rescue fix the failing test with the smallest safe patch
/agy:rescue --resume apply the top fix from the last run
/agy:rescue --background investigate the regression

You can also just ask for a task to be delegated to agy:

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

Pass --model <model>, --effort <low|medium|high>, --agent <agent>, or --mode <accept-edits|plan> to control which model agy uses, how hard it thinks, which custom agent it runs as, and its execution mode:

/agy:rescue --model gemini-3.1-pro-high --effort high investigate why the build is failing in CI

--model and --agent are checked against agy's real model/agent lists (agy --output-format json models/agent) before agy is spawned, so a typo fails fast with the real list of ids instead of agy rejecting it after the fact.

For a substantial implementation request — one that spans more than a file or two, follows a plan you and Claude just worked out, or is underspecified about scope or verification — /agy:rescue normalizes it into a structured contract (Goal, Repository Context, Acceptance Criteria, Files Likely Involved, How to Verify, Guardrails) before handing it to agy, instead of forwarding your raw request as-is. A quick diagnosis ("investigate why the tests started failing") or an unambiguous one-line fix skips this and forwards directly, same as before. After a normalized run finishes, Claude checks the result against that contract's own acceptance criteria before calling it done — see commands/rescue.md for exactly when this triggers and the contract shape. This is prompt-level behavior in commands/rescue.md/skills/agy-cli-runtime, not something agy-companion.mjs enforces in code, so it isn't covered by npm test — only by using /agy:rescue for real.

/agy:status

Shows running and recent agy jobs for the current repository.

/agy:status
/agy:status task-abc123

/agy:result

Shows the final stored agy output for a finished job.

/agy:result
/agy:result task-abc123

/agy:cancel

Cancels an active background agy job.

/agy:cancel
/agy:cancel task-abc123

/agy:setup

Checks whether the agy binary is on PATH, and can toggle the stop-time review gate:

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

Warning

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

Pass --doctor for a deeper diagnostic pass — the kind of thing worth pasting into a bug report instead of asking someone to run several commands by hand:

/agy:setup --doctor
/agy:setup --doctor --json

Adds: the installed agy version against the last one this plugin was verified against (.github/agy-tested-version); which of the flags this plugin depends on (--json-schema, --sandbox, --conversation, etc.) the installed agy --help actually recognizes; whether agy models/agy agent resolve; whether the local job-state directory is writable; whether the current directory is a git repository; and how many jobs are currently active. Everything --doctor adds is free (agy --help and the listing subcommands spend no quota and start no agent turn) — it composes with the tool-permission probe above rather than replacing it.

Differences from codex-plugin-cc

This plugin is a from-scratch port of the structure of the codex Claude Code plugin, adapted to agy's much smaller and simpler CLI surface. It is not a drop-in behavioral clone — this section explains what's actually different before you rely on it for anything Codex's plugin does that this one doesn't.

Two earlier attempts at this same idea exist and are both dead ends: sakibsadmanshajib/gemini-plugin-cc is archived/deprecated, and sakibsadmanshajib/antigravity-plugin has open bug reports that its Claude Code slash commands are silent no-ops and that its documented install command doesn't match its actual marketplace name. This README tries hard not to repeat that pattern — every claim below about what works has now been verified against a real, authenticated agy install (including a live end-to-end /agy:review run), not just documentation or mocked tests; see .github/agy-tested-version for the exact version last verified.

agy (Antigravity CLI) has a smaller CLI surface than Codex's app-server, though a real one — not as thin as it first looked. This section is deliberately explicit about what's actually different, so this plugin doesn't repeat the overpromising that sank the two prior attempts at this idea.

A cautionary tale worth stating up front: this project was first built against third-party spike notes written for agy 1.0.1, which found no native structured-output flag, no --model, and no --effort. Once a real, authenticated agy install (1.1.11 at the time) was available to test against, all three turned out to exist. The CLI moved fast between those two versions and the earlier notes were simply stale by the time this plugin shipped. Every claim below has now been checked against a live agy process — including a real /agy:review run that produced valid, schema-conformant JSON end to end — but if you're reading this on a much newer agy than .github/agy-tested-version, re-verify anything that seems suspicious rather than trusting either this document or the version pinned there.

• Native structured-output enforcement, via --output-format json --json-schema <path>. This was the biggest correction. agy --print --output-format json --json-schema schemas/review-output.schema.json returns a single JSON envelope ({conversation_id, status, response, structured_output, ...}) where structured_output is already schema-conformant — confirmed with a live call that returned exactly the shape requested. /agy:review and /agy:adversarial-review (scripts/lib/agy.mjs's runAgyStructured) use this directly and still run one local validation pass against schemas/review-output.schema.json as defense in depth, but no longer need a prompt-and-retry fallback the way earlier drafts assumed. If a future agy build ever rejects --json-schema as unrecognized, that surfaces as a clear AgyUnsupportedFeatureError pointing at agy update, not a silent fallback.
• --model, --effort, --agent, and --mode are real and forwarded. agy accepts --model <model>, --effort <low|medium|high>, --agent <agent>, and --mode <accept-edits|plan> for a single invocation. /agy:rescue --model <model> --effort <low|medium|high> --agent <agent> --mode <mode> ... forwards all four through to agy. --model and --agent are validated against agy's real lists (agy --output-format json models/agent) before agy is spawned — best-effort only, so an unreachable or older agy just skips the check rather than blocking the run.
• OAuth-only auth, no headless path — but a free way to check login state. agy --print blocks on first use, prints a Google sign-in URL, and waits for you to complete the browser flow and (in the version tested) paste an authorization code back into the terminal — there is no API-key or non-interactive login yet (tracked upstream: google-antigravity/antigravity-cli#78). Because agy-companion always runs agy non-interactively, it cannot complete that prompt itself. scripts/lib/agy.mjs instead watches stdout for the "Authentication required" string, extracts the login URL, and immediately kills the process and surfaces the URL through /agy:status / /agy:result rather than letting the job hang. You still have to open that URL yourself and rerun the command afterward. /agy:setup now also runs a real, free login probe: agy answers -p "/quota" --output-format json as a print-mode command that starts no agent turn and spends no quota (confirmed live against the version in .github/agy-tested-version), so getAgyAuthStatus uses that to report loggedIn: true/false/null instead of only confirming the binary is on PATH.
• No /agy:transfer. Codex's /codex:transfer uses a Codex-specific external-agent session importer to turn a Claude Code transcript into a resumable Codex thread. agy has no documented equivalent, and this plugin does not invent one.
• Per-job resume, targeted by conversation_id. /agy:rescue (the task path) now runs through agy --output-format json too (runAgyText in scripts/lib/agy.mjs), the same envelope /agy:review already used, so it captures a real conversation_id per job instead of running in plain-text mode. --resume/--resume-last looks up this session's most recent finished task job's captured id and resumes it via agy --conversation <id>, confirmed live to target that exact conversation rather than "whatever agy's most-recently-used conversation is" — which matters once a review or another task has run an agy process in between and would otherwise have moved agy's own --continue pointer. A job from before this capture existed has no conversation_id on record, so resuming that one specific job still falls back to --continue.
• No live progress stream. Codex's app-server emits structured item/started / item/completed events (commands running, files being edited, reasoning summaries) that the Codex plugin turns into a live phase indicator. agy --print gives no equivalent — it's silent until it prints the final answer. /agy:status on a running job can only show a raw tail of stdout/stderr as it arrives, not a phase like "editing" or "verifying".
• Best-effort touched-files detection, not a guarantee. For --write task runs, this plugin snapshots git status --porcelain before and after the run and diffs them (captureGitStatusSnapshot / diffGitStatusSnapshots in scripts/lib/agy.mjs) to approximate which files agy touched. Codex's app-server reports this as a structured, authoritative list of file-change items; this plugin's version can miss changes outside a git repository or to gitignored files, can't distinguish agy's edits from unrelated concurrent changes, and — confirmed live — misses a content edit to a file that was already untracked before the run started: git status --porcelain reports an untracked path's mere presence, not whether its content changed, so the same ?? path line appears in both the before and after snapshot and the diff sees nothing.
• Single host: Claude Code only, matching the scope of the reference codex plugin. No Codex-CLI hosting, no native agy plugin-host support, no standalone npx mode — just .claude-plugin/plugin.json.
• What's been live-tested vs. what's still mock-only. Confirmed against a real, authenticated agy install: binary/version detection; full /agy:review --scope working-tree and /agy:adversarial-review --scope working-tree runs (including the disposable-snapshot path, both the inline-diff and large-diff self-collect modes); /agy:rescue foreground and background, /agy:status, /agy:result, and /agy:cancel (confirmed to actually terminate the process, not just flip a status flag); --resume-last (confirmed to attach to a prior conversation, but with a caveat — see docs/TESTING.md for what was actually observed before relying on it); and --conversation <id> targeting a specific past job — confirmed live with a review run deliberately interleaved between two halves of the same task conversation, and the resumed task still recalled the first half's content rather than the review's. --write task execution runs and returns success, but a live run also surfaced a separate, unconfirmed oddity worth flagging: a prompt asking agy to create a new file wrote it under ~/.gemini/antigravity-cli/scratch/ instead of the target repo, reproduced independent of agy-companion by calling agy --print directly — not yet root-caused or worked around here. Still only unit-tested against a mocked child_process.spawn, not a live process: the OAuth-required detection path (every test account used so far was already logged in). See docs/TESTING.md for the current split and what to smoke-test next.

Judgment calls made during the port

A few decisions weren't fully specified by "port codex to drive agy" and needed a call:

• /agy:review needed its own prompt file. Codex's /codex:review doesn't use a prompt template at all — it calls the app-server's built-in review/start RPC, which has no agy equivalent. Since agy has no native reviewer, /agy:review needed a prompt (prompts/review.md) the same way /agy:adversarial-review does; it just wasn't in the original list of files this project's brief said to port over. It's a plain, non-adversarial review-JSON prompt, separate from the adversarial one.
• --add-dir isn't exposed at the command layer. agy --add-dir <path> (repeatable) is real and supported in scripts/lib/agy.mjs, but no /agy:* command surfaces it yet — every run is scoped to the resolved workspace root. Add it to a command's argument-hint if you need multi-directory context.
• conversationResumable now reflects whether a conversationId was actually captured, rather than being hardcoded true for every task job regardless of whether agy's envelope handed back a usable id (see "Per-job resume" above).
• Every review and task job now carries a provenance block (scripts/lib/provenance.mjs, surfaced under provenance in the JSON payload and stored on the job record) — agyVersion, model/effort/agent/mode (when explicitly set; reviews don't expose these at the command layer, so they're null there), conversationId, gitHead, scope, inputHash (the review snapshot's content hash, or a hash of the task prompt), and reviewedPaths. Every field is best-effort and null when not known or not applicable — none are fabricated to fill the shape. Meant for exactly the two questions a confusing result usually turns into: "what agy version/model/scope actually produced this," and "is this the same input as last time, or did something about the repo change." Fetch it via /agy:review --json / /agy:result --json.

Typical Flows

Review Before Shipping

/agy:review

Hand A Problem To agy

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

Start Something Long-Running

/agy:adversarial-review --background
/agy:rescue --background investigate the flaky test

Then check in with:

/agy:status
/agy:result

FAQ

Do I need a separate agy account for this plugin?

If you're already signed into agy on this machine, that login is what this plugin uses — there's no separate agy-companion account or auth layer. If agy isn't signed in yet, the first real command you run will surface a Google OAuth URL through /agy:status; visit it, then rerun the command.

Does the plugin use a separate agy runtime?

No. Every /agy:* command spawns your local agy CLI directly (agy --print ...). There is no shared background runtime or broker process — unlike Codex's app-server, which this plugin's model was built to be simpler than on purpose, since agy has nothing to connect a broker to.

Can I use this without ever authenticating agy?

No. Every command that actually talks to agy requires you to complete agy's Google OAuth flow at least once. /agy:setup will tell you if the binary itself is missing, and will also report whether you're signed in via a free login check.

Testing

See docs/TESTING.md for what npm test covers (arg parsing, state, job control, rendering, process helpers, schema validation, and the agy transport layer with a mocked child_process.spawn) versus what still needs a human with a real, authenticated agy install to verify.

Releasing

Releases are cut by pushing a v* tag, which publishes a GitHub release with notes taken from CHANGELOG.md. See docs/RELEASING.md for the full process, including the four version fields that have to stay in sync and why.

License

Apache-2.0. See LICENSE.