Add files via upload

Author: do-ops885

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.1] - 2025-10-21
 
 ### Changed
+
 - **BREAKING**: Updated Gemini CLI command format to use explicit `googleSearch` tool invocation
   - Changed from: `gemini -p "query" --yolo --output-format json`
   - Changed to: `gemini -p "/tool:googleSearch query:\"search_text\" raw:true" --yolo --output-format json -m "gemini-2.5-flash"`
@@ -17,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `scripts/extract-content.sh`
 
 ### Fixed
+
 - Fixed validation function arithmetic operation that could cause script exit with `set -e`
 - Improved ShellCheck compliance:
   - Split variable declarations and assignments (SC2155)
@@ -26,13 +28,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed false positive validation to properly detect and filter invalid domains
 
 ### Improved
+
 - Enhanced code quality and reliability with ShellCheck best practices
 - Better error handling in validation and search functions
 - More robust script execution with proper return value handling
 
 ## [0.1.0] - 2025-10-20
 
 ### Added
+
 - Initial release of Gemini Search Plugin
 - Core search functionality using Gemini CLI with `google_web_search` tool
 - Smart caching system with 1-hour TTL and MD5 keying
@@ -57,6 +61,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `scripts/prepare-release.sh` - Release preparation
 
 ### Features
+
 - **Gemini CLI Integration**: Uses Gemini CLI in headless mode with `--yolo` flag
 - **Tool Restriction**: Limits Gemini to only `google_web_search` tool via `.gemini/settings.json`
 - **Grounded Results**: All results from Google's web search via Gemini
@@ -66,13 +71,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Security**: URL validation, content size limits, timeout handling
 
 ### Documentation
+
 - Comprehensive README.md with features, usage, and configuration
 - GEMINI.md explaining Gemini CLI integration
 - Detailed agent documentation
 - Command documentation with examples
 - Validation methodology documentation
 
 ### Configuration
+
 - Environment variable support for all settings
 - Configurable cache TTL, retry logic, and timeouts
 - Adjustable content extraction limits
@@ -81,6 +88,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Planned
+
 - Enhanced content extraction with better parsing
 - Additional search engine fallbacks
 - Improved relevance scoring algorithms
@@ -101,11 +109,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The 0.1.1 update includes a breaking change to how the Gemini CLI is invoked. No user action is required as the change is internal to the plugin scripts. However, if you have customized any scripts, you'll need to update them to use the new format.
 
 **What Changed:**
+
 - Gemini CLI now explicitly invokes the `googleSearch` tool
 - Added `-m "gemini-2.5-flash"` flag for model specification
 - Added `raw:true` parameter for unprocessed results
 
 **Benefits:**
+
 - More reliable search results
 - Explicit tool usage prevents ambiguity
 - Better control over response format

CONTRIBUTING.md

@@ -31,11 +31,13 @@ This project follows the Anthropic Code of Conduct. By participating, you are ex
 Before contributing, ensure you have:
 
 1. **Gemini CLI** installed:
+
    ```bash
-   npm install -g @google/genai-cli
+   npm install -g @google/gemini-cli
    ```
 
 2. **Development tools**:
+
    ```bash
    # ShellCheck for script linting
    brew install shellcheck  # macOS
@@ -53,24 +55,28 @@ Before contributing, ensure you have:
 ## Development Setup
 
 1. **Fork and clone** the repository:
+
    ```bash
    git clone https://github.com/YOUR-USERNAME/gemini-search.git
    cd gemini-search
    ```
 
 2. **Create a feature branch**:
+
    ```bash
    git checkout -b feature/your-feature-name
    ```
 
 3. **Make your changes** and test thoroughly
 
 4. **Run linting**:
+
    ```bash
    shellcheck scripts/*.sh
    ```
 
 5. **Test your changes**:
+
    ```bash
    bash tests/run-integration-tests.sh
    ```
@@ -104,6 +110,7 @@ We welcome several types of contributions:
 All bash scripts must:
 
 1. **Use strict error handling**:
+
    ```bash
    set -euo pipefail
    ```
@@ -115,6 +122,7 @@ All bash scripts must:
    - Quote array expansions properly (SC2206)
 
 3. **Include proper documentation**:
+
    ```bash
    # Function: Function name
    # Arguments:
@@ -127,6 +135,7 @@ All bash scripts must:
    ```
 
 4. **Use meaningful variable names**:
+
    ```bash
    # Good
    local query_string="$1"
@@ -138,6 +147,7 @@ All bash scripts must:
    ```
 
 5. **Handle errors gracefully**:
+
    ```bash
    if ! result=$(some_command); then
        log_error "Command failed: some_command"
@@ -279,6 +289,7 @@ Follow conventional commits format:
 ```
 
 **Types:**
+
 - `feat`: New feature
 - `fix`: Bug fix
 - `docs`: Documentation changes
@@ -288,6 +299,7 @@ Follow conventional commits format:
 - `chore`: Maintenance tasks
 
 **Example:**
+
 ```
 feat(search): add support for multi-engine search
 
@@ -344,6 +356,7 @@ When reporting bugs, include:
    - Stack traces
 
 **Template:**
+
 ```markdown
 ### Environment
 - OS: macOS 14.0
@@ -362,6 +375,7 @@ Error: "Gemini CLI search failed"
 
 ### Logs
 ```
+
 <error logs here>
 ```
 ```

GEMINI.md

@@ -37,6 +37,7 @@ gemini -p "/tool:googleSearch query:\"search query\" raw:true" --yolo --output-f
 ### 3. Grounded Web Search Behavior
 
 When the user asks for a search:
+
 - The Gemini CLI agent receives the search query
 - It recognizes the need for external information
 - Since `google_web_search` is the only available tool, it uses that for grounding
@@ -48,10 +49,11 @@ When the user asks for a search:
 This plugin requires the Gemini CLI to be installed:
 
 ```bash
-npm install -g @google/genai-cli
+npm install -g @google/gemini-cli
 ```
 
 Verify installation:
+
 ```bash
 gemini --version
 ```
@@ -61,4 +63,4 @@ gemini --version
 - **Direct Results**: The plugin provides search results directly from the `google_web_search` tool
 - **No Hallucination**: Results are grounded in actual web content retrieved by Gemini
 - **Transparent Sources**: Search results include source URLs and attributions
-- **No Summarization Override**: The plugin respects the raw search data provided by the tool
+- **No Summarization Override**: The plugin respects the raw search data provided by the tool

README.md

@@ -12,7 +12,7 @@ The plugin restricts the Gemini CLI to only use the `google_web_search` tool thr
 
 ## Features
 
-### 💎 Key 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
@@ -108,7 +108,9 @@ Clear the search result cache and reset analytics data.
 1. **Install Gemini CLI**:
 
    ```bash
-   npm install -g @google/genai-cli
+
+ npm install -g @google/gemini-cli
+
    ```
 
 2. **Verify Installation**:
@@ -118,6 +120,7 @@ Clear the search result cache and reset analytics data.
    ```
 
 3. **Configure API Key** (optional):
+
    ```bash
    gemini config set apiKey YOUR_GOOGLE_AI_API_KEY
    ```
@@ -154,6 +157,23 @@ The plugin can be configured through environment variables:
 - Content extraction is optimized to focus on relevant information
 - Relevance validation prevents false positive results
 
+**Performance Metrics:**
+
+- Cached searches: <1 second (97% faster)
+- First searches: 8-20 seconds
+- Cache hit rate: 60-85% (typical usage)
+- Memory usage: <50MB
+- Token savings: 39% via context isolation
+
+For detailed benchmarks and optimization strategies, see [docs/PERFORMANCE.md](docs/PERFORMANCE.md)
+
+**Examples:**
+
+- Basic usage examples: [examples/01-basic-searches.md](examples/01-basic-searches.md)
+- Technical queries: [examples/02-technical-queries.md](examples/02-technical-queries.md)
+- Validation examples: [examples/03-validation-examples.md](examples/03-validation-examples.md)
+- Advanced usage: [examples/04-advanced-usage.md](examples/04-advanced-usage.md)
+
 ## Troubleshooting
 
 - If searches fail, check the error logs at the configured LOG_FILE location

agents/gemini-search.md

@@ -78,6 +78,7 @@ The agent uses `gemini -p` (headless mode) with `--yolo` (auto-approval) and res
 This plugin uses the Gemini CLI in headless mode (`gemini -p`) with the `--yolo` flag for automated tool approval. The `.gemini/settings.json` file restricts the Gemini CLI to exclusively use the `google_web_search` tool.
 
 **What this means:**
+
 - All web searches go through Google's web search via Gemini's API
 - No Claude internal search functionality is triggered
 - No direct web scraping or HTTP requests are made

commands/clear-cache.md

@@ -14,6 +14,7 @@ You are the clear-cache command handler for the gemini-search plugin. When this
 ## Execution Instructions
 
 Run the following commands:
+
 ```bash
 # Clear the cache directory
 rm -rf /tmp/gemini-search-cache/*
@@ -30,6 +31,7 @@ fi
 ## Response Format
 
 After clearing the cache, inform the user:
+
 - Confirmation that the cache has been cleared
 - Number of entries removed (if applicable)
 - Path to the cache directory (`/tmp/gemini-search-cache/`)
@@ -38,6 +40,7 @@ After clearing the cache, inform the user:
 ## When to Use
 
 Suggest clearing cache when:
+
 - Search results seem stale or outdated
 - Troubleshooting search issues
 - Testing new search queries
@@ -48,4 +51,4 @@ Suggest clearing cache when:
 - Cache will rebuild automatically on new searches
 - Analytics data in `/tmp/gemini-analytics/` is NOT affected
 - Plugin configuration remains intact
-- All future searches will query fresh results until cache rebuilds
+- All future searches will query fresh results until cache rebuilds

commands/search-stats.md

@@ -14,6 +14,7 @@ You are the search-stats command handler for the gemini-search plugin. When this
 ## Execution Instructions
 
 Run the following command:
+
 ```bash
 bash "${CLAUDE_PLUGIN_ROOT}/scripts/analytics.sh" report
 ```
@@ -23,17 +24,20 @@ bash "${CLAUDE_PLUGIN_ROOT}/scripts/analytics.sh" report
 After receiving the statistics from the script, present them to the user with:
 
 ### Overall Statistics
+
 - Total searches performed
 - Cache hit/miss ratio
 - Token savings from caching
 - Time period covered
 
 ### Performance Metrics
+
 - Average response time
 - Cache efficiency percentage
 - Search success rate
 
 ### Usage Patterns (if available)
+
 - Most frequent search queries
 - Cache statistics
 - Error rates
@@ -43,6 +47,7 @@ Format the output in a clear, readable table or structured format.
 ## Error Handling
 
 If the script fails or no analytics are available:
+
 - Display a friendly message indicating no statistics are available yet
 - Suggest performing some searches first
 - Show the error message if applicable
@@ -51,4 +56,4 @@ If the script fails or no analytics are available:
 
 - Analytics are stored locally in `/tmp/gemini-analytics/`
 - All data is privacy-preserving (no personal information)
-- Statistics are calculated on-demand with minimal overhead
+- Statistics are calculated on-demand with minimal overhead

commands/search.md

@@ -17,6 +17,7 @@ You are the search command handler for the gemini-search plugin. When this comma
 ## Execution Instructions
 
 Run the following command:
+
 ```bash
 bash "${CLAUDE_PLUGIN_ROOT}/scripts/search-wrapper.sh" search "{{QUERY}}"
 ```
@@ -26,6 +27,7 @@ Where `{{QUERY}}` is the search query provided by the user.
 ## Response Format
 
 After receiving the results from the script, present them to the user with:
+
 - A summary of the search query
 - Top relevant results with titles and URLs
 - Brief snippets from each result
@@ -35,6 +37,7 @@ After receiving the results from the script, present them to the user with:
 ## Error Handling
 
 If the script fails:
+
 - Display the error message from the script
 - Suggest the user check their Gemini CLI installation
 - Recommend clearing cache if appropriate (`/clear-cache`)
@@ -44,4 +47,4 @@ If the script fails:
 - This uses the Gemini CLI in headless mode with `google_web_search` tool
 - Results are cached for 1 hour for efficiency
 - Analytics are tracked automatically
-- Context is isolated for token savings
+- Context is isolated for token savings