diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..21c9c05 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 azmym + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 8450c58..d269770 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # gemini-plugin -**Give Claude Code a second opinion.** Gemini validates your plans, challenges destructive commands, grounds answers in live web data, and audits "done" claims before Claude stops working. +**Give Claude Code a second opinion.** Gemini validates your plans, challenges destructive commands, grounds answers in live web data, reviews diffs, and audits "done" claims before Claude stops working. [![Version](https://img.shields.io/github/v/release/azmym/gemini-plugin?label=version&color=blue)](https://github.com/azmym/gemini-plugin/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) @@ -11,7 +11,7 @@ [![Marketplace: SynthForge](https://img.shields.io/badge/marketplace-SynthForge-orange)](https://github.com/azmym/SynthForge) [![Powered by Gemini](https://img.shields.io/badge/powered%20by-Google%20Gemini-4285F4)](https://aistudio.google.com) -[Quickstart](#install) · [Why use it?](#why-use-it) · [Architecture](#architecture-at-a-glance) · [Slash commands](#slash-commands) · [Auto-triggers](#auto-triggers) · [Documentation](#documentation) +[Quickstart](#install) · [Why use it?](#why-use-it) · [Architecture](#architecture-at-a-glance) · [Slash commands](#slash-commands) · [Subagents](#subagents) · [Skills](#skills) · [Auto-triggers](#auto-triggers) · [Docs](#documentation) @@ -21,7 +21,8 @@ - **Catch mistakes before they ship.** Every plan Claude produces is reviewed by Gemini for gaps and hallucinations before you see it. - **Stop dangerous commands before they run.** When Claude is about to execute `rm -rf`, a force-push, or a `DROP TABLE`, Gemini proposes safer alternatives and can block execution until you decide. -- **Get answers grounded in today's web.** Questions about library versions, recent CVEs, or live API docs are automatically answered with citations, not training-data guesses. +- **Get answers grounded in today's web.** Questions about library versions, recent CVEs, or live API docs are answered with citations, not training-data guesses. +- **Review diffs and PRs.** A dedicated reviewer agent checks changes for security, threading, version drift, doc accuracy, dead code, and complexity. - **Keep context alive across compaction.** Before Claude compacts its context, Gemini summarizes decisions, discarded alternatives, and unresolved debt so the next session picks up cleanly. - **Verify "done" claims.** When Claude says it's finished, Gemini checks the actual output against your original ask and blocks the stop if something was missed. @@ -64,7 +65,7 @@ You will be prompted for your Google AI Studio API key during installation. The The plugin auto-registers the `gemini` MCP server. No separate `claude mcp add` step is needed. -> **Heads up on cost.** As of v0.2.0+ brainstorming is on by default, which means every prompt is grounded with a Gemini call. Combined with v0.3.0's bumped subagent models (Sonnet for validator/researcher, Opus for challenger/summarizer), this is meaningfully more expensive than v0.1.x. If you want to dial it back, run `/gemini-plugin:gemini-brainstorm-off` to fall back to keyword-only grounding. +> **Heads up on cost.** Brainstorming is on by default (since v0.2.0), so every prompt is grounded with a Gemini call. Combined with the subagent model tiers (Sonnet for validator, researcher, and reviewer; Opus for challenger and summarizer), this is meaningfully more expensive than keyword-only grounding. To dial it back, run `/gemini-plugin:gemini-brainstorm-off` to fall back to keyword-triggered grounding. ## What it does for you @@ -85,17 +86,62 @@ The plugin auto-registers the `gemini` MCP server. No separate `claude mcp add` gemini-plugin architecture: three layers (hooks coordinate, subagents reason, MCP executes) connecting Claude Code to Gemini

-Three layers do the work: **hooks** coordinate (read events, apply gates, emit directives), **subagents** reason (validator, challenger, researcher, summarizer, and reviewer with structured JSON verdicts), and the **gemini-mcp** server executes (calls Gemini, Imagen, Veo, and Lyria via Google AI Studio). For the full architecture write-up, see [docs/reference/architecture.md](docs/reference/architecture.md). +Three layers do the work: **hooks** coordinate (read events, apply gates, emit directives), **subagents** reason (validator, challenger, researcher, summarizer, and reviewer, each returning a structured JSON verdict), and the **gemini-mcp** server executes (calls Gemini, Imagen, Veo, and Lyria via Google AI Studio). For the full write-up, see [docs/reference/architecture.md](docs/reference/architecture.md). + +## The `/gemini-plugin:` menu + +When you type `/gemini-plugin:` in Claude Code, the menu shows **two kinds of entries** under one namespace: + +- **Slash commands** (5) run a fixed action immediately, often with arguments (for example `/gemini-plugin:gemini-validate src/auth.ts`). +- **Skills** (9) are capability guides. They load on demand when Claude judges them relevant, and they also appear in the menu so you can invoke one explicitly. Skills tell Claude *when* to reach for Gemini and *which* MCP tool to use. + +The two are separate surfaces: commands are listed below under [Slash commands](#slash-commands); skills under [Skills](#skills). The work itself is carried out by [Subagents](#subagents) and the MCP tools they call. ## Slash commands -| Command | What it does | -|---|---| -| `/gemini-plugin:gemini-validate ` | Ask Gemini to check a file, plan, or claim for gaps and hallucinations | -| `/gemini-plugin:gemini-challenge ` | Get at least two alternatives and a list of objections to any decision | -| `/gemini-plugin:gemini-research ` | Quick web search with citations (add `--deep` for multi-source synthesis) | -| `/gemini-plugin:gemini-brainstorm-off` | Opt out of grounding-on-every-prompt (recommended for chatty sessions to control cost). Falls back to narrow keyword matching. | -| `/gemini-plugin:gemini-brainstorm-on` | Re-enable grounding on every prompt after a previous opt-out (this is the default after install) | +Five commands, all under the `/gemini-plugin:` prefix. + +| Command | Arguments | What it does | +|---|---|---| +| `/gemini-plugin:gemini-validate` | `` | Get a Gemini second opinion on a plan, diff, or claim. Returns gaps, hallucinations, and next actions. Spawns `gemini-validator`. | +| `/gemini-plugin:gemini-challenge` | `` | Get Gemini to argue against the current path and propose at least two alternatives with tradeoffs. Spawns `gemini-challenger`. | +| `/gemini-plugin:gemini-research` | ` [--deep]` | Quick web search with citations; add `--deep` for multi-source synthesis. Spawns `gemini-researcher`. | +| `/gemini-plugin:gemini-brainstorm-off` | (none) | Opt out of grounding-on-every-prompt; fall back to narrow keyword matching. Recommended for chatty sessions to control cost. | +| `/gemini-plugin:gemini-brainstorm-on` | (none) | Re-enable grounding on every prompt after a previous opt-out (this is the default after install). | + +There is no `gemini-review` command: diff review runs through the `gemini-consult` skill, which dispatches the `gemini-reviewer` subagent. See [Subagents](#subagents). + +## Subagents + +Five specialized agents do the reasoning. Each runs in its own context, calls Gemini through the MCP server, and returns a structured JSON verdict. They are spawned automatically by hooks, by a slash command, or by the `gemini-consult` dispatch rule. You can also call one directly, for example `@agent-gemini-plugin:gemini-reviewer review the staged diff`. + +| Subagent | Model | Role | Usually triggered by | +|---|---|---|---| +| `gemini-validator` | Sonnet | Validates plans, diffs, and done-claims against the original ask; flags gaps and hallucinations | Plan-validation hook, done-claim hook, `/gemini-plugin:gemini-validate` | +| `gemini-challenger` | Opus | Devil's advocate: argues alternatives and objections before destructive or architectural decisions | Destructive-command hook, `/gemini-plugin:gemini-challenge` | +| `gemini-researcher` | Sonnet | Search-grounded facts with citations; never opines without a source URL | Prompt-grounding hook, `/gemini-plugin:gemini-research` | +| `gemini-summarizer` | Opus | Builds repo risk maps and compresses session state across compaction | Session-start hook, pre-compact hook | +| `gemini-reviewer` | Sonnet | Generalist diff/PR review: security, threading, version drift, doc accuracy, dead code, complexity | `gemini-consult` dispatch rule (manual, advisory) | + +If a Gemini MCP tool is not available in the session, each agent **fails loud**: it returns `verdict: "unknown"` (the researcher uses `confidence: "unavailable"`) with an `error` field, rather than answering from training data. Full schemas: [docs/reference/subagents.md](docs/reference/subagents.md). + +## Skills + +Nine skills appear under `/gemini-plugin:` and load on demand. Two are routers (decision guides, no MCP tools of their own); seven map to specific Gemini capabilities. + +| Skill | Kind | Use for | +|---|---|---| +| `gemini-when-to-use` | Router | Master router: whether a Gemini consult is warranted, and which capability skill to reach for | +| `gemini-consult` | Router | Routes a consult to the right subagent (researcher, validator, challenger, reviewer, summarizer) and enforces a one-consult-per-turn cap on manual dispatches | +| `gemini-chat-and-reason` | Capability | Second opinions, code review, design critique via `gemini_generate` / `gemini_chat` | +| `gemini-research-grounded` | Capability | Live-web research with citations via `gemini_search_grounded`; deep research via `gemini_start_research` | +| `gemini-file-analysis` | Capability | Multi-modal Q&A over PDFs, images, audio, video, and oversized source files via `gemini_analyze_file` | +| `gemini-code-exec` | Capability | Run Python in Gemini's sandbox to verify math, regex, or algorithms via `gemini_code_execute` | +| `gemini-image-gen` | Capability | Generate images (Nano Banana or Imagen 4) via `gemini_generate_image` | +| `gemini-video-gen` | Capability | Generate short clips with Veo 3.1 (start + poll) via `gemini_start_video` | +| `gemini-audio-tts-music` | Capability | Music (Lyria 3) and text-to-speech via `gemini_generate_music` / `gemini_tts` | + +Full details: [docs/reference/skills.md](docs/reference/skills.md). ## Auto-triggers @@ -104,7 +150,7 @@ These fire without any action on your part: | Trigger | When | What you see | |---|---|---| | Session start | Once per project per day | A risk map of high-fragility zones in your repo | -| Prompt grounding | **On every prompt by default** (opt out with `/gemini-plugin:gemini-brainstorm-off`); after opt-out, only fires on prompts matching narrow patterns like "latest version of X", "CVE-YYYY-NNN", or "changelog for X" | Citations prepended to Claude's answer | +| Prompt grounding | **On every prompt by default** (opt out with `/gemini-plugin:gemini-brainstorm-off`); after opt-out, only on prompts matching narrow patterns like "latest version of X", "CVE-YYYY-NNN", or "changelog for X" | Citations prepended to Claude's answer | | Plan validation | When Claude exits plan mode | A pass or a list of gaps to address before proceeding | | Destructive command | Before `rm -rf`, `--force` pushes, `DROP TABLE`, and similar | Alternatives and a block if a safer path exists | | Pre-compact | Before context compaction | A structured summary of decisions and open work | @@ -118,9 +164,7 @@ These fire without any action on your part: export CLAUDE_PLUGIN_GEMINI_DISABLE_HOOKS=1 ``` -**Disable one specific agent** (for example, if you want validation but not the challenger): - -Add the agent to `permissions.deny` in your Claude Code settings: +**Disable one specific agent** (for example, keep validation but not the challenger). Add the agent to `permissions.deny` in your Claude Code settings: ```json "permissions": { @@ -128,16 +172,14 @@ Add the agent to `permissions.deny` in your Claude Code settings: } ``` -**Brainstorm mode (on by default as of v0.2.0):** - -Every prompt is grounded in live web data. This catches stale-training-data answers but does add a Gemini call (and a small latency hit) to every prompt, even trivial ones. Two ways to manage it: +**Brainstorm mode (on by default).** Every prompt is grounded in live web data, which catches stale-training-data answers but adds a Gemini call (and a small latency hit) to every prompt, even trivial ones. Manage it with: ``` /gemini-plugin:gemini-brainstorm-off # opt out: falls back to keyword-only grounding /gemini-plugin:gemini-brainstorm-on # re-enable after a previous opt-out ``` -When opted out, the grounding hook only fires on prompts that look like questions about post-cutoff information (matching patterns like `latest version of X`, `CVE-YYYY-NNN`, `changelog for X`, `deprecated in X`). +When opted out, the grounding hook only fires on prompts that look like questions about post-cutoff information (patterns like `latest version of X`, `CVE-YYYY-NNN`, `changelog for X`, `deprecated in X`). ## Requirements