Gemini Web Search

Advanced web search using Gemini CLI in headless mode with tool restriction. All searches use Gemini's google_web_search tool.

Quick Start

Basic search:

python .claude/skills/gemini-websearch/scripts/search.py "search for React 19 features"

With validation:

python .claude/skills/gemini-websearch/scripts/search.py "search for TypeScript 5.4 new features" --validate

Batch mode:

python .claude/skills/gemini-websearch/scripts/search.py queries.txt --batch --output results/

View analytics:

python .claude/skills/gemini-websearch/scripts/search.py --show-analytics

Search Workflow

Copy this checklist for research tasks:

Research Progress:

• Step 1: Check cache (1-hour TTL)
• Step 2: Formulate focused search query (prefix with "search ")
• Step 3: Execute headless Gemini search
• Step 4: Parse JSON and extract response content
• Step 5: Validate quality and relevance
• Step 6: Review search success and content quality
• Step 7: Log analytics

Step 1: Check cache MD5-keyed cache with 1-hour TTL. Automatic cleanup on expiry. Tracks cache hit rates.

Step 2: Formulate query Keep queries specific and focused. Break complex questions into multiple targeted searches. Important: Always prefix queries with "search " for best results (e.g., "search for the React 19 best practice").

Step 3: Execute headless search

gemini -p "/tool:google_web_search query:"your query" raw:true"
--yolo --output-format json

The --yolo flag auto-approves tool usage. Returns structured JSON with comprehensive search results.

Step 4: Parse response Extract search results and metadata from JSON output. Note: Gemini CLI doesn't provide citations/grounding metadata in JSON format.

Step 5: Validate results Score based on:

• Content completeness and length

• Search tool success verification

• Response latency (bonus for faster searches)

• Relevance to original query

False positive detection prevents low-quality results. Note: Gemini CLI doesn't provide citations, so validation focuses on content quality metrics.

Step 6: Review sources Verify that the search tool was called successfully and assess content quality directly from the response.

Step 7: Log analytics Track cache hits, latency, quality scores, validation failures, and query patterns.

Advanced Usage

For detailed examples see examples.md

Batch searches with validation:

python .claude/skills/gemini-websearch/scripts/search.py queries.txt
--batch
--output results/
--validate
--min-quality 0.7

Research with retry logic:

python .claude/skills/gemini-websearch/scripts/search.py "complex technical query"
--validate
--min-quality 0.7
--min-relevance 0.6
--retry-on-fail
--max-retries 2

Disable cache for fresh results:

python .claude/skills/gemini-websearch/scripts/search.py "breaking news topic" --no-cache

Clear cache:

python .claude/skills/gemini-websearch/scripts/search.py --clear-cache

Configuration

Required: Tool Restriction

Create/update .gemini/settings.json to restrict Gemini CLI to only google_web_search :

{ "tools": { "exclude": [ "file_read", "file_write", "file_search", "file_list", "web_fetch", "run_shell_command", "save_memory", "code_execution", "edit_file", "create_file", "delete_file", "list_directory", "move_file", "copy_file" ] } }

This ensures Gemini ONLY uses the web search tool, not other capabilities.

Optional: Authentication

Option 1: API key (optional)

export GEMINI_API_KEY="your-api-key"

Option 2: gcloud authentication

gcloud auth login

Option 3: Application Default Credentials

gcloud auth application-default login

Environment Variables

export SEARCH_CACHE_DIR=".cache/gemini-searches" export SEARCH_CACHE_TTL="3600" # 1 hour export ANALYTICS_LOG="search_analytics.json" export GEMINI_MODEL="gemini-2.5-flash"

Config File

Optional ~/.gemini-search/config.json :

{ "model": "gemini-2.5-flash", "cache_enabled": true, "cache_ttl": 3600, "validation": { "enabled": true, "min_quality": 0.6, "min_citations": 0, "min_relevance": 0.5, "retry_on_fail": true, "max_retries": 2 }, "analytics": { "enabled": true, "log_file": "search_analytics.json", "track_cache_hits": true, "track_latency": true, "track_quality": true } }

Command Reference

Single search:

python .claude/skills/gemini-websearch/scripts/search.py "query" [options]

Batch search:

python .claude/skills/gemini-websearch/scripts/search.py queries.txt --batch [options]

Show analytics:

python .claude/skills/gemini-websearch/scripts/search.py --show-analytics

Clear cache:

python .claude/skills/gemini-websearch/scripts/search.py --clear-cache

Options

• --model MODEL

• Gemini model (default: gemini-2.5-flash)

• --no-cache

• Disable caching

• --validate

• Enable result validation

• --min-quality FLOAT

• Minimum quality score (0-1, default: 0.6)

• --min-citations INT

• Minimum citation count (default: 0, not applicable for Gemini CLI)

• --min-relevance FLOAT

• Minimum relevance score (0-1, default: 0.5)

• --retry-on-fail

• Retry if validation fails

• --max-retries INT

• Maximum retry attempts (default: 2)

• --output PATH

• Output file (single) or directory (batch)

• --batch

• Batch mode: query arg is file path

Best Practices

• Use headless mode for programmatic searches

• Restrict tools in settings.json for security

• Enable caching for repeated/related queries

• Validate critical searches before using results

• Monitor analytics to optimize query patterns

• Use batch mode for multi-query research

• Set quality thresholds based on use case

• Always prefix queries with "search " for optimal results

• Assess content quality directly from response text and metadata