{"id":32329873,"url":"https://github.com/d-oit/gemini-search-plugin","last_synced_at":"2026-05-17T06:40:04.835Z","repository":{"id":320143133,"uuid":"1080943803","full_name":"d-oit/gemini-search-plugin","owner":"d-oit","description":"Advanced Claude Code plugin for web search using Gemini CLI with caching, analytics, and validation. Includes comprehensive skills for plugin development.","archived":false,"fork":false,"pushed_at":"2025-10-22T06:00:04.000Z","size":132,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T07:26:48.571Z","etag":null,"topics":["ai-tools","caching","claude-code","claude-code-plugin","gemini","gemini-cli","search-plugin","shell-scripts","web-search"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d-oit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-22T04:57:24.000Z","updated_at":"2025-10-22T06:00:07.000Z","dependencies_parsed_at":"2025-10-22T07:27:09.240Z","dependency_job_id":"96f46eb2-21f2-4747-aee2-9cc95c3ec080","html_url":"https://github.com/d-oit/gemini-search-plugin","commit_stats":null,"previous_names":["d-oit/gemini-search-plugin"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/d-oit/gemini-search-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgemini-search-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgemini-search-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgemini-search-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgemini-search-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d-oit","download_url":"https://codeload.github.com/d-oit/gemini-search-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-oit%2Fgemini-search-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280668405,"owners_count":26370301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","caching","claude-code","claude-code-plugin","gemini","gemini-cli","search-plugin","shell-scripts","web-search"],"created_at":"2025-10-23T18:19:43.164Z","updated_at":"2025-10-23T18:19:46.143Z","avatar_url":"https://github.com/d-oit.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gemini Search Plugin\n\nAdvanced 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.\n\n**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:\n\n- Trigger Claude's internal web search functionality\n- Use direct web scraping or crawling\n- Bypass the Gemini CLI in any way\n\nThe plugin restricts the Gemini CLI to only use the `google_web_search` tool through the `.gemini/settings.json` configuration.\n\n## Features\n\n### 💎 Key Features\n\n- **Gemini CLI Headless Mode** - Uses `gemini -p` with `--yolo` flag for automated web search\n- **Tool Restriction** - `.gemini/settings.json` limits Gemini to only `google_web_search` tool\n- **Grounded Results** - All search results come from Google's web search via Gemini\n- **Subagent Architecture** - Context isolation for 39% better token savings\n- **Smart Caching** - 1-hour TTL with MD5 keying\n- **Auto-retry Logic** - Exponential backoff on failures\n- **Dynamic Content Extraction** - Extract and parse content from websites using Gemini\n- **False Positive Validation** - Validate search results for relevance\n- **Comprehensive Logging** - Detailed logging for debugging and monitoring\n- **3 Slash Commands** - `/search`, `/search-stats`, `/clear-cache`\n- **2 Hooks** - Error detection and pre-edit suggestions\n- **Complete Analytics** - Track usage and token savings\n- **Production Ready** - Error handling, logging, validation\n- **No Web Scraping** - Zero direct HTTP requests or HTML parsing\n\n## Commands\n\n### `/search [query]`\n\nPerform a web search using multiple search engines with smart caching and result validation.\n\n### `/search-stats`\n\nView usage statistics including cache hit rate, top queries, and token savings.\n\n### `/clear-cache`\n\nClear the search result cache and reset analytics data.\n\n## Architecture\n\n### Directory Structure\n\n```\n~/claude-plugins/gemini-search/\n├── .claude-plugin/\n│   └── plugin.json                    # Plugin metadata\n├── agents/\n│   └── gemini-search.md               # Subagent (isolated context)\n├── skills/\n│   └── web-search-patterns/\n│       └── SKILL.md                   # Search best practices\n├── commands/\n│   ├── search.md                      # /search command\n│   ├── search-stats.md                # /search-stats analytics\n│   └── clear-cache.md                 # /clear-cache\n├── scripts/\n│   ├── search-wrapper.sh              # Production wrapper with error handling\n│   ├── analytics.sh                   # Usage tracking and statistics\n│   └── extract-content.sh             # Dynamic content extraction from websites\n├── hooks/\n│   ├── hooks.json                     # Hook config\n│   ├── pre-edit-search.sh             # Pre-edit suggestions with validation\n│   └── error-search.sh                # Auto error detection and handling\n└── README.md                          # Full documentation\n```\n\n## Advanced Features\n\n### Dynamic Content Extraction\n\n- Extracts clean text content from web pages\n- Removes HTML tags, scripts, and styling\n- Validates content relevance to search query\n- Handles multiple content sources with fallback methods\n\n### False Positive Validation\n\n- Validates search results against original query\n- Calculates relevance scores for each result\n- Filters out irrelevant or low-quality content\n- Provides warnings for potentially irrelevant results\n\n### Comprehensive Error Handling\n\n- Retry logic with exponential backoff\n- Multiple search engine fallbacks\n- Network error handling and recovery\n- Graceful degradation when services are unavailable\n\n### Logging System\n\n- Detailed logging of search operations\n- Error logging with context information\n- Performance metrics tracking\n- Audit trail for compliance and debugging\n\n## Getting Started\n\n### Prerequisites\n\n1. **Install Gemini CLI**:\n\n   ```bash\n   npm install -g @google/gemini-cli\n   ```\n\n2. **Verify Installation**:\n\n   ```bash\n   gemini --version\n   ```\n\n3. **Configure API Key** (optional):\n\n   ```bash\n   gemini config set apiKey YOUR_GOOGLE_AI_API_KEY\n   ```\n\n### Usage\n\n1. Install the plugin in your Claude Code environment\n2. The `.gemini/settings.json` file is automatically used to restrict tools\n3. Use `/search [your query]` to perform web searches via Gemini\n4. Check `/search-stats` to monitor usage and cache effectiveness\n5. Use `/clear-cache` if you need to reset cached results\n\n## Configuration\n\nThe plugin can be configured through environment variables:\n\n- `CACHE_TTL`: Cache time-to-live in seconds (default: 3600)\n- `MAX_RETRIES`: Number of retry attempts on failure (default: 3)\n- `RETRY_DELAY`: Initial delay between retries in seconds (default: 1)\n- `BACKOFF_BASE`: Exponential backoff base (default: 2)\n- `LOG_FILE`: Path to main log file (default: /tmp/gemini-search.log)\n- `ERROR_LOG_FILE`: Path to error log file (default: /tmp/gemini-search-errors.log)\n- `SUGGESTIONS_LIMIT`: Number of suggestions to generate (default: 5)\n- `CONTEXT_WINDOW`: Number of previous messages to consider (default: 10)\n- `TIMEOUT_SECONDS`: Content extraction timeout (default: 15)\n- `MAX_CONTENT_SIZE`: Maximum content size to process (default: 100000)\n\n## Performance Notes\n\n- Results are cached for 1 hour to reduce API calls\n- Context isolation helps save tokens by isolating search operations\n- Cache hit rate is tracked to measure effectiveness\n- Error handling with exponential backoff ensures reliability\n- Content extraction is optimized to focus on relevant information\n- Relevance validation prevents false positive results\n\n**Performance Metrics:**\n\n- Cached searches: \u003c1 second (97% faster)\n- First searches: 8-20 seconds\n- Cache hit rate: 60-85% (typical usage)\n- Memory usage: \u003c50MB\n- Token savings: 39% via context isolation\n\nFor detailed benchmarks and optimization strategies, see [docs/PERFORMANCE.md](docs/PERFORMANCE.md)\n\n**Examples:**\n\n- Basic usage examples: [examples/01-basic-searches.md](examples/01-basic-searches.md)\n- Technical queries: [examples/02-technical-queries.md](examples/02-technical-queries.md)\n- Validation examples: [examples/03-validation-examples.md](examples/03-validation-examples.md)\n- Advanced usage: [examples/04-advanced-usage.md](examples/04-advanced-usage.md)\n\n## Troubleshooting\n\n- If searches fail, check the error logs at the configured LOG_FILE location\n- Use `/search-stats` to see if cache hit rate is improving performance\n- If getting rate limited, consider extending the time between searches\n- Use `/clear-cache` if cached results seem outdated\n- Check content extraction logs if web content isn't being parsed correctly\n- Monitor validation warnings for potentially irrelevant results\n\n## Security Considerations\n\n- Content extraction is limited to prevent processing oversized responses\n- URLs are validated to prevent malicious inputs\n- All external requests are made with appropriate timeouts\n- Error messages don't expose sensitive system information\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-oit%2Fgemini-search-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd-oit%2Fgemini-search-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-oit%2Fgemini-search-plugin/lists"}