Skip to content

docs: rewrite README (all commands, subagents, skills) + add MIT LICENSE #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
azmym merged 2 commits into from
May 29, 2026
Merged

docs: rewrite README (all commands, subagents, skills) + add MIT LICENSE #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d29a6f6
docs: rewrite README to cover all commands, subagents, and skills
azmym May 29, 2026
55fb86f
docs: add MIT LICENSE file (declared in manifest, was missing)
azmym May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
82 changes: 62 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)

</div>

Expand All @@ -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.

Expand Down Expand Up @@ -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

Expand All @@ -85,17 +86,62 @@ The plugin auto-registers the `gemini` MCP server. No separate `claude mcp add`
<img src="assets/infographic.png" alt="gemini-plugin architecture: three layers (hooks coordinate, subagents reason, MCP executes) connecting Claude Code to Gemini" width="900" />
</p>

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 <subject>` | Ask Gemini to check a file, plan, or claim for gaps and hallucinations |
| `/gemini-plugin:gemini-challenge <topic>` | Get at least two alternatives and a list of objections to any decision |
| `/gemini-plugin:gemini-research <query>` | 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` | `<file path, pasted text, or description>` | Get a Gemini second opinion on a plan, diff, or claim. Returns gaps, hallucinations, and next actions. Spawns `gemini-validator`. |
| `/gemini-plugin:gemini-challenge` | `<decision, approach, or architecture>` | Get Gemini to argue against the current path and propose at least two alternatives with tradeoffs. Spawns `gemini-challenger`. |
| `/gemini-plugin:gemini-research` | `<query> [--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

Expand All @@ -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 |
Expand All @@ -118,26 +164,22 @@ 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": {
"deny": ["Agent(gemini-plugin:gemini-challenger)"]
}
```

**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

Expand Down
Loading