convez.ai
SkillDesenvolvimento WebIntermediário
arcobaleno64

Gemini Plugin para Claude Code

arcobaleno64/gemini-plugin-cc

Delegate code reviews e debugging para Gemini via Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Skill que delega tarefas de coding e revisões adversariais de código para Google Gemini/AGY diretamente do Claude Code. Implementa comandos slash para debugging, implementação e análise de código com detecção automática de engine e suporte a jobs em background.

Instalação

$npx convez-ai arcobaleno64/gemini-plugin-cc

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
14
Forks
3
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
v0.25.0
Issues abertas
2
Contribuidores
4

Casos de uso

  • Revisão pragmática de diffs e branches buscando bugs reais
  • Revisão adversarial que questiona decisões de design
  • Delegação de tarefas de debugging e implementação em background
  • Análise exploratória de contexto de repositório com modo deep

Veredito

Plugin robusto que estende Claude Code com capacidades de análise e revisão via Gemini, com suporte maduro a jobs async e fallback automático entre engines. Útil para equipes que usam Google Gemini e precisam de integração nativa em fluxos de código.

README

A tradução para o português deste README ainda está na fila.

gemini — Claude Code Plugin

Delegate tasks and adversarial code reviews to Google Gemini / AGY directly from Claude Code.

繁體中文說明 →

Ported from openai/codex-plugin-cc (Apache-2.0) — same slash-command UX, same background job model, same skill contract — powered by the Gemini ecosystem instead of OpenAI.


Features

  • /gemini:rescue — Delegate investigation, debugging, or implementation tasks to Gemini. Runs in the foreground or detached in the background.
  • /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 — Prefers gemini CLI (pipe-safe); falls back to agy.
  • Stdin prompt delivery — Prompts are passed via stdin on all platforms, eliminating shell injection and Windows .cmd wrapper issues.
  • Session lifecycle hooks — Automatically injects GEMINI_COMPANION_SESSION_ID; cleans up stale jobs on session end.

Prerequisites

RequirementVersionInstall
Node.js≥ 18nodejs.org
Gemini CLI≥ 0.40npm install -g @google/gemini-cli
AGY (optional)≥ 1.0.3(see install note below)
Claude Codeanyclaude.ai/code

Install AGY (optional fallback): curl -fsSL https://antigravity.google/cli/install.sh | bash

Authentication: Run gemini once to complete OAuth. No API key is required.

Heads-up (reality check):

  • 2026-06-18: free/personal gemini CLI access ends. After that the gemini engine needs a paid Gemini Code Assist Standard/Enterprise tier; AGY (--engine agy) becomes the free path.
  • Gemini 3.5 (Flash/Pro) is GA on the API but not served by the gemini CLI 0.44.1 (latest) — it returns 404. Use it via the AGY engine (fixed model). The plugin gracefully falls back to a GA model if a requested id is unavailable. See Model Aliases and docs/MODEL_COMPARISON.md.

Installation

Latest (tracks main, auto-updates)

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

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

# 3. Reload plugins
/reload-plugins

Pinned release (a specific published version)

Pin the marketplace to a release tag — e.g. the latest, v0.6.6:

/plugin marketplace add arcobaleno64/gemini-plugin-cc@v0.6.6
/plugin install gemini@gemini-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 install does not auto-update; to move to a newer release, re-add the marketplace with the new tag (e.g. …@v0.6.7).

Then run /gemini:setup — it will check whether Gemini CLI is ready. If Gemini is missing and npm is available, it will offer to install it for you.

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.

FlagDescription
--backgroundRun detached; returns a job ID immediately
--writeAllow Gemini to modify files (--yolo / --dangerously-skip-permissions)
--resume-lastContinue the most recent Gemini session
--freshForce a new Gemini session, ignoring any resumable thread
--engine <gemini|agy|auto>Override engine selection
--model <alias|id>Model override (flash, pro, lite)
--effort <low|medium|high|xhigh>Map effort level to a model

/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.

FlagDescription
--wait / --backgroundRun in the foreground or detached
--deepAgentic 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

/gemini:adversarial-review [focus]

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

FlagDescription
--deepAgentic 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

/gemini:setup

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

/gemini:status [job-id]

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

FlagDescription
--waitBlock until the job completes (requires a job ID)
--allShow 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.


Review Gate (Optional)

An optional stop-time gate that runs an adversarial review before Claude Code can stop, whenever a --write task completed in the session. Disabled by default.

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

AliasResolved ModelNotes
flash / flash3gemini-3-flash-previewLatest Gemini 3 Flash (preview)
pro / pro3gemini-3.1-pro-previewGemini 3.1 Pro (preview)
flash25gemini-2.5-flashStable 2.5 Flash (GA)
pro25gemini-2.5-proStable 2.5 Pro (GA)
lite / fastgemini-2.5-flash-liteCost-efficient (GA)
lite3gemini-3.1-flash-liteGemini 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.
  • Preview IDs may change. Model IDs ending in -preview track Google's preview channel (last verified against gemini CLI 0.44.1). 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 is not on the CLI yet. gemini-3.5-flash and gemini-3.5-pro are GA on the Gemini API but are not served by the gemini CLI 0.44.1 (latest at time of writing) — they return 404 ModelNotFound. To use Gemini 3.5 Flash, route through the AGY engine (--engine agy), which runs it (fixed model; no --model/--effort selection).
  • 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 ignores --model and --effort. agy --print is locked to Gemini 3.5 Flash (High) and exposes no model/effort selection; the plugin prints a note and ignores both flags when --engine agy is active.

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 — fallback; note that AGY in non-interactive mode does not write to a pipe, so explicit --engine agy is required to use it.

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

--model and --effort apply to the gemini engine only. agy --print is locked to Gemini 3.5 Flash (High) and has no model/effort flag, so the plugin ignores --model/--effort when --engine agy is active.

AGY transcript recovery is platform-verified on Windows and macOS; Linux is reported working. Because agy --print does not pipe its output (upstream google-gemini/gemini-cli#27466 — reproduced on macOS agy 1.0.7: 0 bytes reach stdout through a pipe), the plugin recovers AGY responses from the on-disk "brain" transcript under ~/.gemini/antigravity-cli/brain (Windows 1.0.3 and macOS 1.0.7, both verified — same root) or ~/.antigravity-cli/brain (Linux 1.0.2, reported). If --engine agy reports no brain root on your machine, run agy once so it creates the directory, or open an issue with its actual location.


Security

  • Stdin delivery (gemini engine): For the gemini engine, prompts are passed via stdin (Node's spawnSync input option) and never interpolated into a shell string, eliminating shell-injection risk regardless of prompt content. The agy engine has no stdin mode and receives the prompt as a CLI argument, so prefer the default gemini engine for untrusted input.
  • Windows .cmd wrappers: npm installs gemini/agy as .cmd shims, which require shell: true to launch. Because the gemini prompt travels on stdin (never in argv), shell: true never exposes it to cmd.exe parsing — only controlled flags (model id, --yolo, …) are ever placed in argv.
  • 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 positional prompt: AGY has no stdin mode, so under --engine agy the prompt is passed as a positional CLI argument and, on Windows, is subject to cmd.exe quoting. Do not route untrusted prompt content through --engine agy — prefer the default gemini engine.
  • 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: The .omc/ state directory (job logs, session state) is excluded from version control.

Setup & Auth Troubleshooting

SymptomCauseFix
gemini: not foundGemini CLI not installednpm install -g @google/gemini-cli, or run /gemini:setup and accept the install prompt
npm: not foundNode/npm missing from PATHInstall Node.js ≥ 18 from nodejs.org
setup shows gemini auth: No credentials …OAuth not completedRun !gemini once and complete the browser login
setup shows … token expiredOAuth token lapsedRun !gemini again to refresh credentials
Status: partial (AGY fallback only …)Gemini CLI unavailable but AGY presentInstall Gemini CLI, or use --engine agy (its auth cannot be verified)
Windows: command resolves but fails.cmd wrapper / PATHConfirm where gemini resolves; the plugin spawns bare names through shell: true to find .cmd shims
--engine agy reports no brain rootAGY has not created its brain directory yet, or it lives in an unknown locationRun agy once so it creates the brain dir. Known roots: ~/.gemini/antigravity-cli/brain (Windows/macOS, verified) and ~/.antigravity-cli/brain (Linux, reported); if yours differs, open an issue with its location

To authenticate, run !gemini once — the plugin completes OAuth by invoking gemini itself. There is no gemini login subcommand. setup reports ready: true only when Node and the Gemini CLI are present and OAuth is valid; an installed-but-unauthenticated Gemini is reported as not ready.


How It Works

Claude Code
  └─ /gemini:rescue "prompt"
       └─ gemini-companion.mjs task
            ├─ detectEngine()        → gemini | agy
            ├─ buildCliArgs()        → args (no prompt in args for gemini)
            ├─ runCommand()          → spawnSync, prompt via stdin
            │    shell: true (Win)   ← fixes Windows .cmd wrapper
            │    input: prompt       ← gemini engine: prompt via stdin (no shell parsing)
            └─ 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 persisted in .omc/state/ and polled via /gemini:status, so a background result survives even if the Claude session is interrupted.


Parity with codex-plugin-cc

This plugin is a high-fidelity port of openai/codex-plugin-cc. The public slash-command surface, background job model, and state/result/status/cancel flow mirror the upstream; the execution backend is the Gemini CLI (with an AGY fallback) rather than the Codex app server.

Compatibility Matrix

Upstream (Codex)This plugin (Gemini)Parity
/codex:setup/gemini:setupGemini-specific divergence — checks gemini OAuth + optional AGY fallback instead of Codex auth
/codex:review/gemini:reviewbest-effort equivalent — prompt / CLI-adapter review, not a native reviewer
/codex:adversarial-review/gemini:adversarial-reviewbest-effort equivalent — adversarial prompt over the same diff target
/codex:rescue/gemini:rescue1:1 parity — same forwarder/subagent contract and flags
/codex:status/gemini:status1:1 parity — same job model; --all crosses Claude sessions
/codex:result/gemini:resultGemini-specific divergence — surfaces the Gemini session id + gemini resume
/codex:cancel/gemini:cancel1:1 parity — same process-tree termination (POSIX + Windows)

Codex app server vs Gemini CLI adapter

  • Runtime: Codex uses a persistent app-server with native review and persistent threads. This plugin invokes the Gemini CLI directly per command (no shared runtime); AGY is an optional fallback.
  • Standard review: In the Codex plugin, /codex:review is a native reviewer. Here, /gemini:review is a prompt-based / CLI-adapter equivalent — it sends the diff to Gemini with a pragmatic-review prompt and parses structured JSON back. It is not a native Gemini reviewer.
  • Sandbox: Codex exposes read-only / workspace-write sandboxes. Gemini has no equivalent; write access is gated by --write (--yolo), and otherwise the prompt enforces read-only discipline. (--approval-mode plan is intentionally not used: it requires a TTY and conflicts with stdin prompt delivery.)
  • Thread/session resume: Codex persists threads on the app server. Here, resume relies on the Gemini CLI session id captured from the JSON envelope; /gemini:result prints gemini resume <session-id>, and --resume-last continues the latest thread for the current Claude session.

Skills

Three skills are bundled for Claude Code to consume:

SkillPurpose
gemini-cli-runtimeRuntime contract — how to call gemini-companion task
gemini-result-handlingResult presentation rules (severity, reasoning, evidence)
gemini-promptingPrompt composition guide (XML tags, output contract)

Known limitations

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

  • Gemini 3.5 is not served by the gemini CLI, and the free CLI sunsets 2026-06-18. gemini-3.5-* returns 404 on CLI 0.44.1 (reach it via AGY); a requested id that is not served degrades gracefully to the GA fallback gemini-2.5-flash. After 2026-06-18 the free/personal CLI tier ends. 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.

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, the AGY fallback handling, OAuth status checks, and the contract-verification script.

Ver o original no GitHub

Bom para

Relacionados