gemini-search

@happycastle/gemini-search

Web search plugin for Claude Code powered by Gemini CLI. Google Search grounding with structured JSON output, mandatory source citations, and privacy-hardened by default.

Architecture

┌──────────────────────────────────────────────────┐
│                  Claude Code                      │
│                                                   │
│  /search "query"  ──►  skills/web-search/SKILL.md │
│  /research "topic" ──► skills/research/SKILL.md   │
│                                                   │
│         ▼                                         │
│  ┌─────────────────────────┐                      │
│  │  bin/gemini-search.mjs  │ ◄── Added to PATH    │
│  │                         │                      │
│  │  • Search-optimized     │                      │
│  │    system prompt        │                      │
│  │  • Mandatory citations  │                      │
│  │  • Privacy auto-disable │                      │
│  └───────────┬─────────────┘                      │
└──────────────┼───────────────────────────────────-┘
               ▼
┌──────────────────────────┐
│       Gemini CLI         │
│  --output-format json    │
│  --prompt "..."          │
│                          │
│  google_web_search ──►   │
│  Grounded response       │
└──────────────────────────┘

Install

Prerequisites

Install and authenticate Gemini CLI:

npm install -g @google/gemini-cli
gemini  # authenticate on first run

As a Claude Code plugin (recommended)

Inside Claude Code, add this repo as a marketplace and install the plugin:

/plugin marketplace add happycastle114/gemini-search
/plugin install gemini-search@happycastle-gemini

That's it. /search, /research, and the web-search / research skills are now available.

To update later:

/plugin marketplace update happycastle-gemini

Alternative: install from a local clone

git clone https://github.com/happycastle114/gemini-search.git

Then in Claude Code:

/plugin marketplace add ./gemini-search
/plugin install gemini-search@happycastle-gemini

Alternative: standalone CLI via npm

If you only want the gemini-search binary (no Claude Code plugin):

npm install -g @happycastle/gemini-search
gemini-search "latest Node.js LTS version"

Note: claude plugin install @happycastle/gemini-search does not work — Claude Code plugins are distributed via marketplace catalogs (.claude-plugin/marketplace.json), not npm package names. Use the marketplace flow above.

Usage

Slash Commands

Once installed, Claude Code gains two slash commands:

Command	Description
/search <query>	Quick web search with citations
/research <topic>	Multi-step deep research workflow

Skills (Auto-triggered)

The plugin includes two skills that Claude Code activates automatically:

• web-search — Triggers on "search the web", "look up", "find online", "what's the latest", "current version of"
• research — Triggers on "research", "deep dive", "investigate thoroughly", "comprehensive analysis"

MCP Tool (Native model invocation)

Installing this plugin auto-registers a Model Context Protocol (MCP) server so the model can invoke web search natively, the same way it would call a built-in tool. No .mcp.json editing required — the plugin's plugin.json declares the server and Claude Code wires it up on /plugin install.

Tool name	When the model uses it
gemini_web_search	Auto-invoked whenever the model needs current/real-world info: latest versions, recent news, live docs, evolving best practices, anything that may have changed since training cutoff.

The tool returns the same citation-validated markdown the CLI does ([Source](URL) inline + ## Sources block, byte-identical to grounding URLs, set-equality enforced). Set raw: true in the tool arguments to get the raw Gemini JSON envelope instead.

The MCP server is the same gemini-search pipeline (privacy override, anti-hallucination citation contract, tool-invocation evidence gating) — just exposed over stdio JSON-RPC so the model's tool router can call it directly.

You can also wire the MCP server into another MCP-aware client (Cursor, Windsurf, raw Claude Desktop, etc.) by pointing it at the bundled binary: