Gemini Search Plugin
Advanced web search plugin using the Gemini CLI in headless mode with google_web_search tool restriction, providing caching, analytics, content extraction, and validation for Claude Code.
Important: This plugin uses the Gemini CLI with the google_web_search tool exclusively via headless mode (gemini -p with --yolo flag). It does NOT:
- Trigger Claude's internal web search functionality
- Use direct web scraping or crawling
- Bypass the Gemini CLI in any way
The plugin restricts the Gemini CLI to only use the google_web_search tool through the .gemini/settings.json configuration.
Features
💎 Key Features
- Gemini CLI Headless Mode - Uses
gemini -p with --yolo flag for automated web search
- Tool Restriction -
.gemini/settings.json limits Gemini to only google_web_search tool
- Grounded Results - All search results come from Google's web search via Gemini
- Subagent Architecture - Context isolation for 39% better token savings
- Smart Caching - 1-hour TTL with MD5 keying
- Auto-retry Logic - Exponential backoff on failures
- Dynamic Content Extraction - Extract and parse content from websites using Gemini
- False Positive Validation - Validate search results for relevance
- Comprehensive Logging - Detailed logging for debugging and monitoring
- 3 Slash Commands -
/search, /search-stats, /clear-cache
- 2 Hooks - Error detection and pre-edit suggestions
- Complete Analytics - Track usage and token savings
- Production Ready - Error handling, logging, validation
- No Web Scraping - Zero direct HTTP requests or HTML parsing
Commands
/search [query]
Perform a web search using multiple search engines with smart caching and result validation.
/search-stats
View usage statistics including cache hit rate, top queries, and token savings.
/clear-cache
Clear the search result cache and reset analytics data.
Architecture
Directory Structure
~/claude-plugins/gemini-search/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── agents/
│ └── gemini-search.md # Subagent (isolated context)
├── skills/
│ └── web-search-patterns/
│ └── SKILL.md # Search best practices
├── commands/
│ ├── search.md # /search command
│ ├── search-stats.md # /search-stats analytics
│ └── clear-cache.md # /clear-cache
├── scripts/
│ ├── search-wrapper.sh # Production wrapper with error handling
│ ├── analytics.sh # Usage tracking and statistics
│ └── extract-content.sh # Dynamic content extraction from websites
├── hooks/
│ ├── hooks.json # Hook config
│ ├── pre-edit-search.sh # Pre-edit suggestions with validation
│ └── error-search.sh # Auto error detection and handling
└── README.md # Full documentation
Advanced Features
Dynamic Content Extraction
- Extracts clean text content from web pages
- Removes HTML tags, scripts, and styling
- Validates content relevance to search query
- Handles multiple content sources with fallback methods
False Positive Validation
- Validates search results against original query
- Calculates relevance scores for each result
- Filters out irrelevant or low-quality content
- Provides warnings for potentially irrelevant results
Comprehensive Error Handling
- Retry logic with exponential backoff
- Multiple search engine fallbacks
- Network error handling and recovery
- Graceful degradation when services are unavailable
Logging System
- Detailed logging of search operations
- Error logging with context information
- Performance metrics tracking
- Audit trail for compliance and debugging
Getting Started
Prerequisites
-
Install Gemini CLI:
npm install -g @google/gemini-cli
-
Verify Installation:
gemini --version
-
Configure API Key (optional):
gemini config set apiKey YOUR_GOOGLE_AI_API_KEY
Usage
- Install the plugin in your Claude Code environment
- The
.gemini/settings.json file is automatically used to restrict tools
- Use
/search [your query] to perform web searches via Gemini
- Check
/search-stats to monitor usage and cache effectiveness
- Use
/clear-cache if you need to reset cached results
Configuration
The plugin can be configured through environment variables:
apmantza
JuliusBrussee