agy-plugin-cc — Gemini CLI / Antigravity CLI Companion for Claude Code

agy-plugin-cc is a Claude Code companion for running Gemini CLI or Antigravity CLI (agy) as a cross-model task delegate and code reviewer, with pragmatic and adversarial review, MCP tools, and background jobs.

繁體中文說明 → · FAQ: English / 繁體中文

Ported from openai/codex-plugin-cc (Apache-2.0), retaining a familiar slash-command and background-job workflow while adapting behavior to Gemini/AGY capabilities and documenting intentional divergences.

Independent project. agy-plugin-cc is community-maintained and is not affiliated with, endorsed by, or sponsored by Google LLC or Anthropic. "Gemini" and "Antigravity" are trademarks of Google LLC and "Claude" is a trademark of Anthropic; all are used here only to name the tools this plugin works with. You install and authenticate those tools yourself, and their terms govern what they do with what is sent to them.

Related project

agy-security-audit is a separate Antigravity CLI (agy) plugin for evidence-backed, multi-stage security assurance and vulnerability verification. It runs natively inside Antigravity CLI. Neither project is bundled with or required by the other.

---

Start here

You need Claude Code, Node.js ≥ 18, and one supported engine: Gemini CLI ≥ 0.40 or AGY ≥ 1.1.12. Install and authenticate the engine you choose; you do not need both. Gemini CLI requires a Standard/Enterprise account or an API key, while AGY is the practical default for personal accounts. See Prerequisites for the supported versions and authentication details.

Install from the release channel

/plugin marketplace add arcobaleno64/agy-plugin-cc
/plugin install gemini@agy-plugin-cc
/reload-plugins

Verify the selected engine with /gemini:setup --engine agy for AGY, or /gemini:setup for auto/Gemini. See Installation for explicit updates and pinned releases.

Three common workflows

Goal	Command
Pragmatic review of the current change	/gemini:review --wait
Adversarial challenge of a design decision	/gemini:adversarial-review --wait Focus on the retry logic
Background delegation of a longer task	/gemini:rescue --background Investigate the failing tests

Use /gemini:status and /gemini:result <job-id> to collect a background result. See Commands for the complete interface and engine-specific behavior.

---

Why this plugin?

agy-plugin-cc is a Claude Code-native companion bridge for users who want both Gemini CLI and Antigravity CLI (agy) support during Google's Gemini CLI transition.

See the measured Gemini / Antigravity plugin comparison for the project's scope and deliberate trade-offs.

Compared with AGY-only, multi-host plugins, this project keeps the Gemini CLI path where available while providing an explicit --engine agy route for users migrating to Antigravity CLI.

• Claude Code-native /gemini:* slash commands.
• Pragmatic and adversarial code review over the current diff or branch.
• Background task delegation for longer-running companion-agent work.
• Gemini model aliases, graceful model fallback, and transient review retry.
• One declared AGY floor (1.1.12) in place of seven compatibility gates: an older AGY is refused by name, not silently degraded.
• Stdin prompt delivery on both engines — prompts never enter argv.

Need	Use this plugin when...
Gemini CLI still works for you	You want model selection, JSON output, and stdin prompt delivery.
You are migrating to AGY	Use --engine agy as the fully supported Antigravity CLI backend.
You want adversarial review	Use /gemini:adversarial-review with optional focus text.
You need AGY-only multi-host support	Consider an AGY-only plugin instead.

---

Features

• /gemini:rescue — Delegate investigation, debugging, or implementation tasks to the selected Gemini CLI or AGY engine. Runs in the foreground or detached in the background.
• /gemini:transfer — Export current session context (git status, diff, instructions) into a structured JSON snapshot and print a single-quoted launch command for AGY or Gemini CLI (POSIX Bash form everywhere, plus a PowerShell form on Windows).
• /gemini:review — Standard (pragmatic) code review over the current diff or branch. Finds real bugs, missing error handling, and incomplete code paths. Add --deep for an agentic pass that explores repo context beyond the diff.
• /gemini:adversarial-review — Adversarial code review that challenges design decisions over the current diff or branch. Returns structured findings with severity ratings.
• /gemini:setup — Check Gemini CLI / AGY availability and OAuth status.
• /gemini:status — Inspect active and completed background jobs.
• /gemini:result / /gemini:cancel — Retrieve or cancel a background job.
• Engine auto-detection — Both engines are first-class; auto checks gemini first for its JSON/model contract, then agy.
• Stdin prompt delivery on both engines — the prompt never enters argv, so no platform argv limit can truncate it and no metacharacter in it can be reinterpreted.
• Session lifecycle hooks — Automatically injects GEMINI_COMPANION_SESSION_ID. On session end it terminates this session's still-running background jobs and removes their records; jobs from other sessions are left alone. Finished jobs' results are discarded with them, so retrieve anything you still need with /gemini:result before the session ends.

---

Prerequisites

Requirement	Version	Install
Node.js	≥ 18	nodejs.org
Gemini CLI	≥ 0.40; required for the gemini engine	npm install -g @google/gemini-cli
AGY	≥ 1.1.12 (enforced); live-verified on 1.1.24, Windows and Ubuntu WSL2. Older AGY is refused with the version it found and the command that fixes it — below 1.1.12, --model and --effort are accepted and then ignored in headless runs, a prompt starting with / is executed as a command, and there is no JSON envelope to read the answer from. Run agy update.	(see install note below)
Claude Code	any	claude.ai/code

Install AGY (required for --engine agy): curl -fsSL https://antigravity.google/cli/install.sh | bash

Authentication: Each engine authenticates independently. Run gemini once for the Gemini engine, or run agy once interactively for the AGY engine. AGY 1.1.10+ also supports Application Default Credentials (ADC) and Gemini Enterprise / Workforce Identity Federation (WIF), and 1.1.13+ accepts GEMINI_API_KEY with modelProvider: "gemini" in its settings.json — a settings-file route, which is why it appears in no agy --help output. AGY OAuth authentication cannot be verified reliably from a headless setup probe, so /gemini:setup --engine agy reports it as unknown until a real AGY command succeeds. --probe-agy settles it, and is verified on both an interactive login and a GEMINI_API_KEY route (AGY 1.1.15, isolated home, unkeyed control): keyed it reports verified, unkeyed it reports unknown with AGY's own diagnostic rather than a false logout. ADC and Enterprise/WIF are untested — treat a logged-out verdict on a working account there as a bug worth reporting.

The Gemini engine now needs a Standard/Enterprise account or an API key. Google ended consumer Gemini CLI access on 2026-06-18. On a personal account, gemini CLI 0.53.1 still installs and answers --version, but every request returns API key not valid (API_KEY_INVALID) — verified 2026-08-04. The AGY engine is unaffected and is the practical default; pass --engine agy, or set GEMINI_ENGINE=agy, if auto selects an unauthenticated gemini binary.

Heads-up (reality check):

• 2026-06-18 consumer transition: Google announced that free/personal, Google AI Pro, and Google AI Ultra Gemini CLI requests stop being served after this date; Standard/Enterprise access remains. See Google's Gemini CLI to Antigravity CLI announcement.
• Model availability drifts by CLI version. A 2026-08-05 probe of the live Gemini API listing found gemini-3.5-flash and gemini-3.6-flash are now GA, while gemini-3.5-pro is still absent — the 2026-06-02 probe had returned 404 ModelNotFound for both 3.5 ids. The plugin gracefully falls back to a GA model if a requested id is unavailable. See Model Aliases and docs/MODEL_COMPARISON.md.

---

Installation

Release channel (marketplace follows main)

# 1. Add the marketplace
/plugin marketplace add arcobaleno64/agy-plugin-cc

# 2. Install the plugin
/plugin install gemini@agy-plugin-cc

# 3. Reload plugins
/reload-plugins

This marketplace source follows the repository's main branch, but that does not mean every Claude Code launch automatically installs and activates new code:

• Claude Code identifies this plugin by its explicit manifest version. Existing installations update only after that version is bumped (normally as part of a release); unversioned commits on main with the same manifest version are not delivered as plugin updates.
• Auto-update is disabled by default for third-party marketplaces. To opt in, open /plugin, select Marketplaces → agy-plugin-cc, and choose Enable auto-update. When enabled, Claude Code checks the marketplace at startup and updates installed plugins whose resolved version changed.
• If Claude Code reports that the plugin was updated, run /reload-plugins before using it in the current session. Opening Claude Code by itself is therefore not a reliable guarantee that a newly published version is already active.

For an explicit update without enabling auto-update, run:

/plugin marketplace update agy-plugin-cc
/plugin update gemini@agy-plugin-cc
/reload-plugins

Pinned release (a specific published version)

Pin the marketplace to a release tag — e.g. v0.24.1:

/plugin marketplace add arcobaleno64/[email protected]
/plugin install gemini@agy-plugin-cc
/reload-plugins

Claude Code installs plugins from the git tree, not from GitHub Release tarballs — @<tag> selects the git tag behind a Release. A pinned marketplace stays on that tag even if marketplace auto-update is enabled. To move it to another release, remove the existing marketplace (which also uninstalls plugins installed from it), add the repository again with the new tag, reinstall the plugin, and run /reload-plugins.

Then run /gemini:setup for auto/Gemini, or /gemini:setup --engine agy for AGY. The selected engine is the only engine dependency that must be installed; setup offers the matching installer when it is missing.

If Gemini is installed but not authenticated yet, run:

!gemini

---

Quick Start

# Delegate a task to Gemini (foreground)
/gemini:rescue Investigate why the auth middleware returns 401 on valid tokens

# Run in the background and check later
/gemini:rescue --background Add unit tests for the UserService class
/gemini:status

# Adversarial review of your current diff
/gemini:adversarial-review

# Review with a specific focus
/gemini:adversarial-review Focus on race conditions in the job queue

---

Commands

/gemini:rescue [prompt]

Delegates a task to Gemini. Reads from stdin if no prompt is given.

Flag	Description
--background	Run detached; returns a job ID immediately
--write	State that edits are expected. Off by default. On gemini it adds --yolo, which genuinely gates whether write tools exist. On AGY it selects --new-project over --add-dir; both orient the run on your repository and neither withholds write, so there it is a statement of intent, not a boundary — see Security
--resume-last	Continue the most recent Gemini session. Refused with --write on the gemini engine: gemini --resume accepts only latest or an index, so it cannot name a conversation, and the run it continues may belong to another project — which would receive the edits. Use --engine agy (which pins by id), or resume without --write.
--fresh	Force a new Gemini session, ignoring any resumable thread
--engine <gemini|agy|auto>	Override engine selection
--model <alias|id>	Model override. Gemini resolves its aliases; AGY 1.1.10+ requires an exact model ID from agy models. AGY model selection cannot be combined with --effort or a dual-engine (--engines gemini,agy) review.
--effort <low|medium|high|xhigh>	Gemini maps effort to a model; AGY 1.1.10+ forwards low, medium, or high as native reasoning effort when no AGY model is selected.

/gemini:transfer [instructions...]

Exports current workspace context (git diff, status, instructions) and generates ready-to-run CLI commands (agy/gemini) to hand off work to an interactive terminal session. Includes automated secret redaction (.env*, credentials) and git conflict safeguards. The generated commands are printed for you to paste into a terminal; the plugin never runs them.

Flag	Description
--engine <gemini|agy|auto>	Which handoff commands to print. auto (default) prints both
--model <id>	Model override carried into the generated command. AGY requires an exact ID from agy models
--effort <low|medium|high|xhigh>	Reasoning effort carried into the generated AGY command. Cannot be combined with --model. AGY accepts only low, medium, high — xhigh produces a command AGY rejects. The generated gemini command carries no effort flag at all

/gemini:review

Runs a standard, pragmatic review over the current working tree or branch diff — real bugs, missing error handling, and incomplete code paths. Not steerable and takes no focus text; use /gemini:adversarial-review to challenge a specific decision.

Flag	Description
--wait / --background	Run in the foreground or detached
--deep	Agentic review — let Gemini explore repo context beyond the diff (slower, higher-token; gemini engine)
--base <ref>	Compare against a specific git ref
--scope <auto|working-tree|branch>	Diff scope
--engine <gemini|agy|auto>	Override engine
--model <alias|id>	Model override
--effort <level>	Model selection on Gemini; native reasoning effort on AGY 1.1.10+ (low, medium, high) when no AGY model is selected
--engines gemini,agy	Run both engines concurrently as independent blind reviews. Mutually exclusive with --engine, and cannot be combined with an AGY model selection

/gemini:adversarial-review [focus]

Runs an adversarial review over the current working tree or branch diff.

Flag	Description
--deep	Agentic review — let Gemini explore repo context beyond the diff (slower, higher-token; gemini engine)
--base <ref>	Compare against a specific git ref
--scope <auto|working-tree|branch>	Diff scope
--engine <gemini|agy|auto>	Override engine
--model <alias|id>	Model override
--effort <level>	Model selection on Gemini; native reasoning effort on AGY 1.1.10+ (low, medium, high) when no AGY model is selected

/gemini:setup

Prints availability and auth status for Node, Gemini CLI, and AGY.

Flag	Description
--engine <agy|gemini>	Report readiness for that engine rather than the auto-routing default
--probe-agy	Verify AGY's login by asking it a read-only question. Free — the account answers /quota without starting a turn. Every AGY this plugin runs is new enough; the probe declines only when the version string cannot be read at all, and setup says so
--probe-gemini	Verify the stored Gemini credential by making a real request. Not free — it costs nothing when the credential is already broken (the API refuses it before generating), but it spends a turn when the credential works. Skipped, with a note, under --engine agy
--enable-review-gate / --disable-review-gate	Toggle the stop-time review gate (see Review Gate)

Without a probe, Gemini readiness is read off disk, which can only prove staleness: a present-but-expired oauth_creds.json reports partial, while a credential living only in the OS keychain cannot be judged at all (gemini CLI 0.53.1 migrates the file into the keychain and deletes it). geminiCredentialSource names which credential actually satisfied the check.

/gemini:status [job-id]

Lists active and recent background jobs. Pass a job ID to inspect a single job.

Flag	Description
--wait	Block until the job completes (requires a job ID). Gives up after 4 minutes and reports the job's state at that point — the job itself keeps running, so re-run --wait or collect it later with /gemini:result
--all	Show all jobs, not just this session's

/gemini:result [job-id]

Retrieves the output of a completed job. If the job has a Gemini session ID, the output includes Resume in Gemini: gemini --resume <session-id> — paste that into a terminal to continue the session in Gemini CLI directly.

/gemini:cancel [job-id]

Cancels a running or queued background job.

---

MCP Tools

The plugin also ships an MCP server (.mcp.json → scripts/gemini-mcp.mjs), so an agent can drive it without a human typing a slash command. This surface is not a mirror of the commands above — read the two tables together before assuming a feature is reachable.

Tool	Required	Optional	Guaranteed read-only	Reaches Google
gemini_rescue	workspace, prompt	write, model, effort, engine, timeout	no	yes
gemini_review	workspace	base, scope, model, engine, deep, timeout	no	yes
gemini_adversarial_review	workspace	base, scope, model, engine, deep, focus, timeout	no	yes
gemini_job_status	workspace, jobId	—	yes	no
gemini_job_result	workspace, jobId	—	yes	no
gemini_job_cancel	workspace, jobId	—	no	no

workspace is required on every tool and must be an absolute path to an existing directory. There is no implicit "current directory" here: the server is launched once per session from .mcp.json, not per invocation from a shell.

The first three queue a background job and return immediately with a jobId. Nothing arrives with that response — poll gemini_job_status, then collect with gemini_job_result. A job started and never collected is quota spent for nothing, which is this plugin's most expensive failure mode.

A no-write dispatch is an intent, not a sandbox. gemini_rescue defaults write to false, and the two review tools expose no write option, but AGY has no enforced read-only mode, so any of the three turns can still edit files. The run compares the workspace before and after and reports what it wrote. All three therefore advertise readOnlyHint: false and destructiveHint: true: annotations describe the worst a tool can do and cannot vary with arguments. See docs/THREAT-MODEL.md §7.2.

The three job tools are addressed by job id and deliberately cross sessions. A caller holding an id has already identified the job, so the session filter that keeps the discovery paths honest cannot do any work for them — and applying it broke them outright, because this server never receives a session id (see below).

Jobs queued here belong to no session. .mcp.json gives the server no way to learn GEMINI_COMPANION_SESSION_ID: the SessionStart hook can only export into CLAUDE_ENV_FILE, which reaches later Bash commands, not a server started alongside them. Before v0.18.0 those untagged jobs were sorted with "another session's" and were invisible to /gemini:status and uncancellable from the slash commands. They are shown now — "nobody could say whose it is" is not the same claim as "it is someone else's".

Slash-only, by omission

Listed so the gap is visible rather than discovered: /gemini:setup and its probe flags (interactive by design), /gemini:transfer (it writes a workspace-local snapshot and needs the model to author the instructions file), --resume-last, and --engines gemini,agy are not on this surface — use the slash command or the CLI. Each of the three turn-spending MCP tools accepts an integer timeout; when omitted, the per-engine default applies. Every gemini_rescue starts a fresh turn. The Review Gate is configured through /gemini:setup, and the setting is stored per workspace, so it persists across sessions and must be enabled again in each repository.

---

Review Gate (Optional)

An optional gate that runs an adversarial review before Claude Code can stop, whenever a --write task completed or returned partial output. Disabled by default; partial counts because edits may already exist.

Three things about its scope are easy to get wrong:

• It runs at the end of every agent turn, not once when the session ends — Claude Code's Stop hook fires per turn.
• The --write task it looks for is any one in this workspace, not only one from the current session (stop-review-gate-hook.mjs reads the whole workspace job store). A write task queued through the MCP tools carries no session id and is never cleaned up at session end, so it keeps arming the gate until the 50-job store evicts it.
• The enable/disable setting is per workspace and lives on disk, so it survives restarts and must be enabled again in each repository.

Enable or disable via /gemini:setup:

# Enable
/gemini:setup --enable-review-gate

# Disable
/gemini:setup --disable-review-gate

When enabled and the review returns needs-attention, Claude Code is blocked from stopping and shown the finding summary. Run /gemini:adversarial-review --wait to review the findings and decide whether to accept or fix them before continuing.

---

Model Aliases

Alias	Resolved Model	Notes
flash / flash3	gemini-3-flash-preview	Gemini 3 Flash (preview)
pro / pro3	gemini-3.1-pro-preview	Gemini 3.1 Pro (preview)
flash25	gemini-2.5-flash	Stable 2.5 Flash (GA)
pro25	gemini-2.5-pro	Stable 2.5 Pro (GA)
lite / fast	gemini-2.5-flash-lite	Cost-efficient (GA)
lite3	gemini-3.1-flash-lite	Gemini 3.1 Flash-Lite (GA, cost-efficient)

Model Alias Notes

• Aliases and effort tiers live in a single source of truth — plugins/gemini/scripts/lib/model-map.mjs — and npm test verifies the table above against it, so the two cannot drift.
• Effort mapping (applied when --effort is given without --model): none/minimal → gemini-2.5-flash-lite; low/medium → gemini-3-flash-preview; high/xhigh → gemini-3.1-pro-preview.
• CLI probe snapshot. The alias table was last re-verified 2026-08-05 against the live Gemini API model listing; all six ids it uses resolved. Google can retire preview ids at any time. If an alias stops resolving, override it with --model <exact-id> — any value that is not a known alias is passed through to the CLI unchanged.
• Gemini 3.5 availability has changed. The 2026-06-02 probe returned 404 ModelNotFound for both gemini-3.5-flash and gemini-3.5-pro. As of 2026-08-05 gemini-3.5-flash is GA and gemini-3.5-pro is still absent. Unknown or unavailable model IDs degrade gracefully to the GA fallback.
• Graceful model fallback. If a requested model id is not found on your gemini CLI (preview/retired id, or a CLI-version mismatch), the plugin retries the run once on the GA fallback gemini-2.5-flash and prints a clear note — so a stale id degrades gracefully instead of hard-failing.
• AGY 1.1.10+ model and reasoning selection. Use either --model <exact-id> from agy models or native --effort <low|medium|high>; the options are mutually exclusive. AGY model IDs are not Gemini aliases, and --model is unavailable for a dual-engine review because model IDs are engine-specific.

---

Engine Routing

In auto mode the plugin selects the first available engine in this order:

1. gemini CLI — outputs via stdout; supports stdin prompt delivery.
2. agy — first-class supported engine and second auto candidate; receives the prompt on stdin with no --print flag. AGY below the declared floor (1.1.12) is refused at detection.

Override via --engine flag or the GEMINI_ENGINE environment variable.

Gemini counts as available only when it has a credential the CLI would actually use. That means GEMINI_API_KEY/GOOGLE_API_KEY, ~/.gemini/oauth_creds.json, or the two entries Gemini CLI 0.53.1 keeps in your OS keychain (gemini-cli-api-key/default-api-key, gemini-cli-oauth/main-account). The keychain is checked for existence only — never the stored value — and the probe can be switched off with GEMINI_COMPANION_DISABLE_KEYCHAIN=1, at the cost of auto skipping a gemini whose credential it can no longer see. See PRIVACY.md. One case is deliberately not detected: where no keychain is available the CLI falls back to an encrypted file shared by every service, and its presence cannot distinguish a gemini credential from an unrelated token, so it is not guessed at — use --engine gemini there.

AGY 1.1.10+ selection: use either --model <exact-id> from agy models or --effort <low|medium|high>. Gemini aliases are not valid AGY model IDs, model and effort cannot be combined, and --model is unavailable for a dual-engine review because IDs are engine-specific. Gemini retains its separate alias and effort-to-model mapping.

AGY answers in a native JSON envelope. --output-format stream-json returns the response, conversation ID, and a terminal status on stdout, plus the progress events that make a cut-off run legible. That envelope is the source of truth, and no brain root is required. One consequence: the reasoning-summary section is not shown for AGY results, because the envelope reports only a thinking_tokens count and carries no thinking text. The Gemini engine is unaffected; it takes its reasoning summary from stderr.

The on-disk transcript is still read, but for one case only and never as a version fallback: AGY killed before it printed anything. The turn ran, it was billed, and the transcript is the only surviving copy of what it produced. A run that prints its envelope never touches it. Known brain roots are ~/.gemini/antigravity-cli/brain and ~/.antigravity-cli/brain; if neither exists, that salvage path simply does not fire and the run reports the timeout it actually hit.

---

Security

• Stdin delivery: every prompt, on both engines, uses Node's spawnSync input option and never enters argv. The positional path and its 24,000-character limit are gone with the AGY floor — the versions that needed them are refused at engine detection.
• Windows process boundary: Gemini's npm .cmd shim is launched through shell:true, but its prompt remains on stdin and only validated flags enter argv. AGY must resolve to an absolute .exe and is always launched with shell:false.
• Git process boundary: Repository-derived refs are always passed to Git as literal argv with shell:false, including on Windows; Git helpers never inherit the .cmd wrapper fallback. This aligns with the upstream Codex plugin's v1.0.6 Git shell-expansion removal.
• DEP0190 warning is benign: On Windows you may see (node:NNN) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated. This is safe to ignore here — the deprecation is about prompt content placed in argv under shell: true, but this plugin never does that for the gemini engine: the prompt travels on stdin, and only controlled flags reach argv (each validated, e.g. model ids must match ^[A-Za-z0-9][A-Za-z0-9._-]*$). The warning is Node flagging the general pattern, not an actual injection vector in this code path.
• AGY sandbox is not enabled: AGY 1.1.10 added a .git rule under --sandbox, but that flag is not a filesystem path boundary and this plugin deliberately never passes it. Reviews and delegated tasks therefore receive no .git protection from that mode.
• Credential handling: OAuth credentials in ~/.gemini/oauth_creds.json are read only to check token expiry via getGeminiLoginStatus(); they are never logged, copied elsewhere, or transmitted by this plugin.
• .gitignore: A transfer snapshot's gitDiff field holds the entire uncommitted diff, so /gemini:transfer writes .omc/.gitignore containing * when it creates the directory — the snapshots are excluded from version control in your repository, not only in this one. Before v0.19.0 the exclusion existed only in this repository's own , so elsewhere the snapshots were untracked rather than ignored and committed them. An existing is never overwritten. Job state and logs live outside the repository entirely — see .

What is sent, kept, and read — including the one path that transmits without an explicit command — is documented in PRIVACY.md.

---

Setup & Auth Troubleshooting

Symptom	Cause	Fix
gemini: not found	Gemini CLI not installed	npm install -g @google/gemini-cli, or run /gemini:setup and accept the install prompt
npm: not found	Node/npm missing from PATH	Install Node.js ≥ 18 from nodejs.org
setup shows gemini auth: No credentials …	OAuth not completed	Run !gemini once and complete the browser login
setup shows … token expired	OAuth token lapsed	Run !gemini again to refresh credentials
Status: partial (AGY available …)	Gemini CLI unavailable but AGY present	Use --engine agy directly; setup keeps AGY auth unknown because it cannot verify the independent AGY OAuth flow non-interactively
Windows: command resolves but fails	.cmd wrapper / PATH	Confirm where gemini resolves; the plugin spawns bare names through shell: true to find .cmd shims
--engine agy reports no brain root	AGY has not created its brain directory yet, or it lives in an unknown location	Run agy once so it creates the brain dir. Known roots: ~/.gemini/antigravity-cli/brain (verified on Windows, macOS AGY 1.0.7, and Linux AGY 1.1.2) and ~/.antigravity-cli/brain (older Linux 1.0.2, reported); if yours differs, open an issue with its location

For the Gemini engine, run !gemini once — the plugin completes OAuth by invoking gemini itself. There is no gemini login subcommand. For the AGY engine, run agy interactively once, or give it a non-interactive credential (ADC/WIF on 1.1.10+, GEMINI_API_KEY with modelProvider: "gemini" on 1.1.13+); its separate OAuth state is not inferred from Gemini's ~/.gemini/oauth_creds.json. setup reports AGY as partial while the binary is present but auth remains unverifiable.

---

How It Works

Claude Code
  └─ /gemini:rescue "prompt"
       └─ gemini-companion.mjs task
            ├─ detectEngine()        → gemini | agy
            ├─ buildCliArgs()        → version-gated args
            ├─ runCommand()          → spawnSync
            │    input: prompt       ← gemini + AGY ≥1.1.2
            └─ renderTaskResult()   → Markdown output to Claude

Background mode spawns a detached worker child process (task-worker for /gemini:rescue, review-worker for /gemini:review and /gemini:adversarial-review) and returns a job ID immediately. State is polled via /gemini:status, so a background result survives even if the Claude session is interrupted.

Job state is written to Claude Code's per-plugin data directory — $CLAUDE_PLUGIN_DATA/state/<workspace>-<hash>/, holding state.json and one .json plus .log per job, most recent 50 kept. A 51st job deletes the oldest finished one, and its result is then gone — /gemini:result cannot retrieve it, whether or not you ever read it. The plugin prints a warning naming what it removed, so this is never silent; a queued or running job is never evicted. Outside Claude Code, where that variable is unset, it falls back to <system temp>/gemini-companion/<workspace>-<hash>/; the OS eventually cleans that, so a job left running across a temp sweep can disappear. Set GEMINI_COMPANION_DATA to pin the location yourself.

The workspace-local .omc/ directory is a separate thing: it holds /gemini:transfer snapshots only, not job state.

---

Parity with codex-plugin-cc

A high-fidelity port of openai/codex-plugin-cc: the slash-command surface, background job model, and state/result/status/cancel flow mirror the upstream, while the execution backends are the Gemini CLI and AGY engines rather than the Codex app server.

The per-command compatibility matrix and the runtime, review, sandbox and resume differences are in docs/parity.md. Dated audits against specific upstream versions sit beside it.

---

Skills

Three skills are bundled for Claude Code to consume:

Skill	Purpose
gemini-cli-runtime	Runtime contract — how to call gemini-companion task
gemini-result-handling	Result presentation rules (severity, reasoning, evidence)
gemini-prompting	Prompt composition guide (XML tags, output contract)

---

Known limitations

Documented, non-blocking constraints — see the linked sections for detail:

• Model and access availability drift. Google announced the 2026-06-18 consumer Gemini CLI transition; Gemini model IDs served by the CLI also change over time. This plugin keeps a GA fallback for unavailable Gemini model IDs. See Model Alias Notes and docs/MODEL_COMPARISON.md.
• /gemini:review is a prompt/CLI adapter, not a native reviewer. It sends the diff with a review prompt and parses the structured JSON, rather than using an app-server reviewer, so its feedback depth differs from a native one. See Codex app server vs Gemini CLI adapter.

---

Support

• Setup or auth failing — check Setup & Auth Troubleshooting first; most install and OAuth symptoms are in that table.
• A feature behaves differently from codex-plugin-cc — check docs/known-diffs.md before filing. Several differences are deliberate and documented.
• A bug — open a bug report. Include the exact command and your /gemini:setup output; those two answer most questions on their own.
• An engine version or platform we have not verified — open a compatibility report. "It works on X" is as useful as "it breaks on X", because the docs only claim what has actually been run.
• A security vulnerability — do not open an issue. Use private disclosure; see SECURITY.md.
• Anything else, or you cannot use GitHub — email [email protected]. GitHub is the faster route for anything that belongs in public, because the answer stays where the next person will find it.

This is a single-maintainer project, not a staffed support desk. Everything above reaches one person.

Deeper material lives in docs/, which separates reference kept current from dated records that are never rewritten — reading one as the other is the easiest mistake to make there.

Reviewing the plugin rather than using it? docs/verifying-without-credentials.md is the complete offline path — no account, no API key. For a run of every command end to end against a stand-in engine, start with node scripts/reviewer-demo.mjs.

---

Versioning

This plugin is 0.x by intent, not by neglect. Its surface — slash commands, MCP tool names and schemas, hook behavior, flags — tracks two upstream CLIs that are themselves shipping behavior changes every few weeks, and the plugin cannot be more stable than what it drives.

While at 0.x:

• MINOR (0.23.0 → 0.24.0) may carry a breaking change to that surface. When it does, the CHANGELOG entry says so in its first line.
• PATCH (0.23.0 → 0.23.1) never does.

Engine support policy

The supported engine versions are the ones in Prerequisites, and for AGY that floor is enforced at engine detection rather than documented and hoped for: an older AGY is refused by name, with the version found and the command that fixes it.

The floor moves only when a capability the plugin depends on requires it — never to keep pace with upstream releases for their own sake. When it moves, it moves in a MINOR release whose CHANGELOG entry names the new floor and the upgrade command in its first line. There is no support window measured in time: an AGY that still does what the plugin asks of it stays supported however old it is.

1.0.0 is reserved for the point where that surface has gone three consecutive MINOR releases without a breaking change, and the AGY integration no longer needs per-version gates. The second is now true: the seven supportsAgy* gates are gone, replaced by one floor checked once in detectEngine, and no path branches on the AGY version after that. The first is not: the breaking change that removed them is the unreleased 0.25.0, so the count starts again from there.

---

Changelog

See CHANGELOG.md.

---

License & Upstream Attribution

MIT © 2026 arcobaleno64.

This project is a derivative work of openai/codex-plugin-cc, Copyright 2026 OpenAI, licensed under the Apache License, Version 2.0. Adapted portions remain under Apache-2.0 (see LICENSE-APACHE-2.0 and NOTICE); Gemini/AGY-specific changes are MIT (see LICENSE).

Derived from upstream (adapted, Apache-2.0): the slash-command structure, the background job model (enqueue / worker / status / result / cancel), the .omc/state persistence and job-control patterns, the stop-time review-gate pattern, the skill contract layout, and the version/manifest tooling (bump-version).

Original to this repository (MIT): the Gemini/AGY engine detection and routing, stdin prompt delivery, the model-map alias/effort source, AGY engine handling, OAuth status checks, and the contract-verification script.