内容
# 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.
[繁體中文說明 →](README.zh-TW.md) · FAQ: [English](docs/FAQ.md) / [繁體中文](docs/FAQ.zh-TW.md)
Ported from [openai/codex-plugin-cc](https://github.com/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`](https://github.com/arcobaleno64/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](#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](#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](#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](docs/COMPARISON.md) 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](https://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](https://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](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/).
> - **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](#model-aliases) and [docs/MODEL_COMPARISON.md](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/agy-plugin-cc@v0.24.1
/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](https://github.com/arcobaleno64/agy-plugin-cc/releases). 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](#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](#review-gate-optional)) |
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`](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](#review-gate-optional) 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`](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](https://github.com/openai/codex-plugin-cc/releases/tag/v1.0.6).
- **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 `.gitignore`, so elsewhere the snapshots were untracked rather than ignored and `git add -A` committed them. An existing `.omc/.gitignore` is never overwritten. Job state and logs live outside the repository entirely — see [How It Works](#how-it-works).
**What is sent, kept, and read** — including the one path that transmits without an explicit command — is documented in [`PRIVACY.md`](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](https://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](https://github.com/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`](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](#model-alias-notes) and [docs/MODEL_COMPARISON.md](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](#codex-app-server-vs-gemini-cli-adapter).
---
## Support
- **Setup or auth failing** — check [Setup & Auth Troubleshooting](#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](docs/known-diffs.md) before filing. Several differences are deliberate and documented.
- **A bug** — open a [bug report](https://github.com/arcobaleno64/agy-plugin-cc/issues/new?template=bug_report.yml). 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](https://github.com/arcobaleno64/agy-plugin-cc/issues/new?template=compatibility_report.yml). "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](https://github.com/arcobaleno64/agy-plugin-cc/security/advisories/new); see [`SECURITY.md`](SECURITY.md).
- **Anything else, or you cannot use GitHub** — email <arcobaleno830623@gmail.com>. 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/`](docs/README.md), 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`](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](#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](plugins/gemini/CHANGELOG.md).
---
## License & Upstream Attribution
MIT © 2026 arcobaleno64.
This project is a derivative work of [openai/codex-plugin-cc](https://github.com/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`](LICENSE-APACHE-2.0) and [`NOTICE`](NOTICE)); Gemini/AGY-specific changes are MIT (see [`LICENSE`](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.
连接信息
猜你喜欢
暂无推荐服务器