├── README.md ├── SKILL.md ├── reference.md ├── templates.md ├── tools.md └── patterns.md /README.md: -------------------------------------------------------------------------------- 1 | # Gemini CLI Skill for Claude Code 2 | 3 | A Claude Code skill that enables effective use of Google's Gemini CLI as a powerful auxiliary tool. 4 | 5 | ## What This Skill Does 6 | 7 | This skill teaches Claude Code how to wield Gemini CLI for: 8 | 9 | - **Code Generation** - Create apps, components, and modules 10 | - **Code Review** - Security audits, bug detection, improvements 11 | - **Test Generation** - Unit tests, integration tests 12 | - **Documentation** - JSDoc, README, API docs 13 | - **Web Research** - Current information via Google Search 14 | - **Architecture Analysis** - Codebase investigation and mapping 15 | 16 | ## Installation 17 | 18 | Copy the skill directory to your Claude Code skills folder: 19 | 20 | ```bash 21 | # Clone the repo 22 | git clone https://github.com/forayconsulting/gemini_cli_skill.git 23 | 24 | # Copy to Claude Code skills directory 25 | cp -r gemini_cli_skill ~/.claude/skills/gemini-cli 26 | ``` 27 | 28 | Or manually create `~/.claude/skills/gemini-cli/` and copy the files. 29 | 30 | ## Prerequisites 31 | 32 | - [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed 33 | - Gemini API key or OAuth authentication configured 34 | 35 | ```bash 36 | # Install Gemini CLI 37 | npm install -g @google/gemini-cli 38 | 39 | # Authenticate 40 | gemini # First run prompts for auth 41 | ``` 42 | 43 | ## Files 44 | 45 | | File | Purpose | 46 | |------|---------| 47 | | `SKILL.md` | Main skill definition - when to use, core instructions | 48 | | `reference.md` | Complete CLI command and flag reference | 49 | | `templates.md` | Reusable prompt templates for common tasks | 50 | | `patterns.md` | Integration patterns and workflows | 51 | | `tools.md` | Gemini's built-in tools documentation | 52 | 53 | ## Usage 54 | 55 | Once installed, Claude Code automatically uses this skill when appropriate. Just ask: 56 | 57 | ``` 58 | "Use Gemini to review this code for security issues" 59 | "Have Gemini generate tests for this module" 60 | "Ask Gemini what's new in TypeScript 5.5" 61 | "Get Gemini to analyze this codebase architecture" 62 | ``` 63 | 64 | ## Key Features 65 | 66 | ### Prompt Templates 67 | 68 | Ready-to-use templates for: 69 | - Code generation (single-file, multi-file, components) 70 | - Code review (comprehensive, security, performance) 71 | - Test generation (unit, integration) 72 | - Documentation (JSDoc, README, API) 73 | 74 | ### Integration Patterns 75 | 76 | - **Generate-Review-Fix** - Quality assurance cycle 77 | - **Background Execution** - Parallel task processing 78 | - **Model Selection** - Pro vs Flash decision tree 79 | - **Rate Limit Handling** - Strategies for free tier limits 80 | 81 | ### Gemini's Unique Tools 82 | 83 | - `google_web_search` - Real-time internet search 84 | - `codebase_investigator` - Deep architecture analysis 85 | - `save_memory` - Cross-session persistence 86 | 87 | ## Quick Reference 88 | 89 | ```bash 90 | # Basic generation 91 | gemini "Create [description]" --yolo -o text 92 | 93 | # Code review 94 | gemini "Review [file] for bugs and security issues" -o text 95 | 96 | # Web research 97 | gemini "What's new in [topic]? Use Google Search." -o text 98 | 99 | # Architecture analysis 100 | gemini "Use codebase_investigator to analyze this project" -o text 101 | 102 | # Faster model for simple tasks 103 | gemini "[prompt]" -m gemini-2.5-flash -o text 104 | ``` 105 | 106 | ## Why Use Gemini from Claude Code? 107 | 108 | | Use Case | Benefit | 109 | |----------|---------| 110 | | Second opinion | Different AI perspective on code | 111 | | Current info | Google Search grounding | 112 | | Architecture | codebase_investigator tool | 113 | | Parallel work | Offload tasks while continuing | 114 | 115 | ## License 116 | 117 | MIT 118 | -------------------------------------------------------------------------------- /SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: gemini-cli 3 | description: Wield Google's Gemini CLI as a powerful auxiliary tool for code generation, review, analysis, and web research. Use when tasks benefit from a second AI perspective, current web information via Google Search, codebase architecture analysis, or parallel code generation. Also use when user explicitly requests Gemini operations. 4 | allowed-tools: 5 | - Bash 6 | - Read 7 | - Write 8 | - Grep 9 | - Glob 10 | --- 11 | 12 | # Gemini CLI Integration Skill 13 | 14 | This skill enables Claude Code to effectively orchestrate Gemini CLI (v0.16.0+) with Gemini 3 Pro for code generation, review, analysis, and specialized tasks. 15 | 16 | ## When to Use This Skill 17 | 18 | ### Ideal Use Cases 19 | 20 | 1. **Second Opinion / Cross-Validation** 21 | - Code review after writing code (different AI perspective) 22 | - Security audit with alternative analysis 23 | - Finding bugs Claude might have missed 24 | 25 | 2. **Google Search Grounding** 26 | - Questions requiring current internet information 27 | - Latest library versions, API changes, documentation updates 28 | - Current events or recent releases 29 | 30 | 3. **Codebase Architecture Analysis** 31 | - Use Gemini's `codebase_investigator` tool 32 | - Understanding unfamiliar codebases 33 | - Mapping cross-file dependencies 34 | 35 | 4. **Parallel Processing** 36 | - Offload tasks while continuing other work 37 | - Run multiple code generations simultaneously 38 | - Background documentation generation 39 | 40 | 5. **Specialized Generation** 41 | - Test suite generation 42 | - JSDoc/documentation generation 43 | - Code translation between languages 44 | 45 | ### When NOT to Use 46 | 47 | - Simple, quick tasks (overhead not worth it) 48 | - Tasks requiring immediate response (rate limits cause delays) 49 | - When context is already loaded and understood 50 | - Interactive refinement requiring conversation 51 | 52 | ## Core Instructions 53 | 54 | ### 1. Verify Installation 55 | 56 | ```bash 57 | command -v gemini || which gemini 58 | ``` 59 | 60 | ### 2. Basic Command Pattern 61 | 62 | ```bash 63 | gemini "[prompt]" --yolo -o text 2>&1 64 | ``` 65 | 66 | Key flags: 67 | - `--yolo` or `-y`: Auto-approve all tool calls 68 | - `-o text`: Human-readable output 69 | - `-o json`: Structured output with stats 70 | - `-m gemini-2.5-flash`: Use faster model for simple tasks 71 | 72 | ### 3. Critical Behavioral Notes 73 | 74 | **YOLO Mode Behavior**: Auto-approves tool calls but does NOT prevent planning prompts. Gemini may still present plans and ask "Does this plan look good?" Use forceful language: 75 | - "Apply now" 76 | - "Start immediately" 77 | - "Do this without asking for confirmation" 78 | 79 | **Rate Limits**: Free tier has 60 requests/min, 1000/day. CLI auto-retries with backoff. Expect messages like "quota will reset after Xs". 80 | 81 | ### 4. Output Processing 82 | 83 | For JSON output (`-o json`), parse: 84 | ```json 85 | { 86 | "response": "actual content", 87 | "stats": { 88 | "models": { "tokens": {...} }, 89 | "tools": { "byName": {...} } 90 | } 91 | } 92 | ``` 93 | 94 | ## Quick Reference Commands 95 | 96 | ### Code Generation 97 | ```bash 98 | gemini "Create [description] with [features]. Output complete file content." --yolo -o text 99 | ``` 100 | 101 | ### Code Review 102 | ```bash 103 | gemini "Review [file] for: 1) features, 2) bugs/security issues, 3) improvements" -o text 104 | ``` 105 | 106 | ### Bug Fixing 107 | ```bash 108 | gemini "Fix these bugs in [file]: [list]. Apply fixes now." --yolo -o text 109 | ``` 110 | 111 | ### Test Generation 112 | ```bash 113 | gemini "Generate [Jest/pytest] tests for [file]. Focus on [areas]." --yolo -o text 114 | ``` 115 | 116 | ### Documentation 117 | ```bash 118 | gemini "Generate JSDoc for all functions in [file]. Output as markdown." --yolo -o text 119 | ``` 120 | 121 | ### Architecture Analysis 122 | ```bash 123 | gemini "Use codebase_investigator to analyze this project" -o text 124 | ``` 125 | 126 | ### Web Research 127 | ```bash 128 | gemini "What are the latest [topic]? Use Google Search." -o text 129 | ``` 130 | 131 | ### Faster Model (Simple Tasks) 132 | ```bash 133 | gemini "[prompt]" -m gemini-2.5-flash -o text 134 | ``` 135 | 136 | ## Error Handling 137 | 138 | ### Rate Limit Exceeded 139 | - CLI auto-retries with backoff 140 | - Use `-m gemini-2.5-flash` for lower priority tasks 141 | - Run in background for long operations 142 | 143 | ### Command Failures 144 | - Check JSON output for detailed error stats 145 | - Verify Gemini is authenticated: `gemini --version` 146 | - Check `~/.gemini/settings.json` for config issues 147 | 148 | ### Validation After Generation 149 | Always verify Gemini's output: 150 | - Check for security vulnerabilities (XSS, injection) 151 | - Test functionality matches requirements 152 | - Review code style consistency 153 | - Verify dependencies are appropriate 154 | 155 | ## Integration Workflow 156 | 157 | ### Standard Generate-Review-Fix Cycle 158 | 159 | ```bash 160 | # 1. Generate 161 | gemini "Create [code]" --yolo -o text 162 | 163 | # 2. Review (Gemini reviews its own work) 164 | gemini "Review [file] for bugs and security issues" -o text 165 | 166 | # 3. Fix identified issues 167 | gemini "Fix [issues] in [file]. Apply now." --yolo -o text 168 | ``` 169 | 170 | ### Background Execution 171 | 172 | For long tasks, run in background and monitor: 173 | ```bash 174 | gemini "[long task]" --yolo -o text 2>&1 & 175 | # Monitor with BashOutput tool 176 | ``` 177 | 178 | ## Gemini's Unique Capabilities 179 | 180 | These tools are available only through Gemini: 181 | 182 | 1. **google_web_search** - Real-time internet search via Google 183 | 2. **codebase_investigator** - Deep architectural analysis 184 | 3. **save_memory** - Cross-session persistent memory 185 | 186 | ## Configuration 187 | 188 | ### Project Context (Optional) 189 | 190 | Create `.gemini/GEMINI.md` in project root for persistent context that Gemini will automatically read. 191 | 192 | ### Session Management 193 | 194 | List sessions: `gemini --list-sessions` 195 | Resume session: `echo "follow-up" | gemini -r [index] -o text` 196 | 197 | ## See Also 198 | 199 | - `reference.md` - Complete command and flag reference 200 | - `templates.md` - Prompt templates for common operations 201 | - `patterns.md` - Advanced integration patterns 202 | - `tools.md` - Gemini's built-in tools documentation 203 | -------------------------------------------------------------------------------- /reference.md: -------------------------------------------------------------------------------- 1 | # Gemini CLI Command Reference 2 | 3 | Complete reference for Gemini CLI v0.16.0+ 4 | 5 | ## Installation 6 | 7 | ```bash 8 | npm install -g @google/gemini-cli 9 | # Or without installing: 10 | npx @google/gemini-cli 11 | ``` 12 | 13 | ## Authentication 14 | 15 | ```bash 16 | # Option 1: API Key 17 | export GEMINI_API_KEY=your_key 18 | 19 | # Option 2: OAuth (interactive) 20 | gemini # First run prompts for auth 21 | ``` 22 | 23 | ## Command Line Flags 24 | 25 | ### Essential Flags 26 | 27 | | Flag | Short | Description | 28 | |------|-------|-------------| 29 | | `--yolo` | `-y` | Auto-approve all tool calls | 30 | | `--output-format` | `-o` | Output format: `text`, `json`, `stream-json` | 31 | | `--model` | `-m` | Model selection (e.g., `gemini-2.5-flash`) | 32 | 33 | ### Session Management 34 | 35 | | Flag | Short | Description | 36 | |------|-------|-------------| 37 | | `--resume` | `-r` | Resume session by index or "latest" | 38 | | `--list-sessions` | | List available sessions | 39 | | `--delete-session` | | Delete session by index | 40 | 41 | ### Execution Options 42 | 43 | | Flag | Short | Description | 44 | |------|-------|-------------| 45 | | `--sandbox` | `-s` | Run in isolated sandbox | 46 | | `--approval-mode` | | `default`, `auto_edit`, or `yolo` | 47 | | `--timeout` | | Request timeout in ms | 48 | | `--checkpointing` | | Enable file change snapshots | 49 | 50 | ### Context & Tools 51 | 52 | | Flag | Description | 53 | |------|-------------| 54 | | `--include-directories` | Add directories to workspace | 55 | | `--allowed-tools` | Restrict available tools | 56 | | `--allowed-mcp-server-names` | Restrict MCP servers | 57 | 58 | ### Other Options 59 | 60 | | Flag | Short | Description | 61 | |------|-------|-------------| 62 | | `--debug` | `-d` | Enable debug output | 63 | | `--version` | `-v` | Show version | 64 | | `--help` | `-h` | Show help | 65 | | `--list-extensions` | `-l` | List installed extensions | 66 | | `--prompt-interactive` | `-i` | Interactive mode with initial prompt | 67 | 68 | ## Output Formats 69 | 70 | ### Text (`-o text`) 71 | ```bash 72 | gemini "prompt" -o text 73 | # Returns: Human-readable response 74 | ``` 75 | 76 | ### JSON (`-o json`) 77 | ```bash 78 | gemini "prompt" -o json 79 | ``` 80 | 81 | Returns structured data: 82 | ```json 83 | { 84 | "response": "The actual response content", 85 | "stats": { 86 | "models": { 87 | "gemini-2.5-flash": { 88 | "api": { 89 | "totalRequests": 3, 90 | "totalErrors": 0, 91 | "totalLatencyMs": 5000 92 | }, 93 | "tokens": { 94 | "prompt": 1500, 95 | "candidates": 500, 96 | "total": 2000, 97 | "cached": 800, 98 | "thoughts": 150, 99 | "tool": 50 100 | } 101 | } 102 | }, 103 | "tools": { 104 | "totalCalls": 2, 105 | "totalSuccess": 2, 106 | "totalFail": 0, 107 | "byName": { 108 | "google_web_search": { 109 | "count": 1, 110 | "success": 1, 111 | "durationMs": 3000 112 | } 113 | } 114 | } 115 | } 116 | } 117 | ``` 118 | 119 | ### Stream JSON (`-o stream-json`) 120 | Real-time newline-delimited JSON events for monitoring long tasks. 121 | 122 | ## Model Selection 123 | 124 | ### Available Models 125 | 126 | | Model | Use Case | Context | 127 | |-------|----------|---------| 128 | | `gemini-3-pro` | Complex tasks (default) | 1M tokens | 129 | | `gemini-2.5-flash` | Quick tasks, lower latency | Large | 130 | | `gemini-2.5-flash-lite` | Fastest, simplest tasks | Medium | 131 | 132 | ### Usage 133 | ```bash 134 | # Default (Pro) 135 | gemini "complex analysis" -o text 136 | 137 | # Flash for speed 138 | gemini "simple task" -m gemini-2.5-flash -o text 139 | ``` 140 | 141 | ## Configuration Files 142 | 143 | ### Settings Location 144 | Priority order (highest first): 145 | 1. `/etc/gemini-cli/settings.json` (system) 146 | 2. `~/.gemini/settings.json` (user) 147 | 3. `.gemini/settings.json` (project) 148 | 149 | ### Example Settings 150 | ```json 151 | { 152 | "security": { 153 | "auth": { 154 | "selectedType": "oauth-personal" 155 | } 156 | }, 157 | "general": { 158 | "previewFeatures": true, 159 | "vimMode": false, 160 | "checkpointing": true 161 | }, 162 | "mcpServers": {} 163 | } 164 | ``` 165 | 166 | ### Project Context (GEMINI.md) 167 | 168 | Create `.gemini/GEMINI.md` in project root: 169 | ```markdown 170 | # Project Context 171 | 172 | Project description and guidelines. 173 | 174 | ## Coding Standards 175 | - Standards Gemini should follow 176 | 177 | ## When Making Changes 178 | - Guidelines for modifications 179 | ``` 180 | 181 | ### Ignore Files (.geminiignore) 182 | 183 | Like `.gitignore`, excludes files from context: 184 | ``` 185 | node_modules/ 186 | dist/ 187 | *.log 188 | .env 189 | ``` 190 | 191 | ## Session Management 192 | 193 | ### List Sessions 194 | ```bash 195 | gemini --list-sessions 196 | ``` 197 | 198 | Output: 199 | ``` 200 | Available sessions for this project (5): 201 | 1. Create task manager (10 minutes ago) [uuid] 202 | 2. Review code (20 minutes ago) [uuid] 203 | ... 204 | ``` 205 | 206 | ### Resume Session 207 | ```bash 208 | # By index 209 | echo "follow-up question" | gemini -r 1 -o text 210 | 211 | # Latest session 212 | echo "continue" | gemini -r latest -o text 213 | ``` 214 | 215 | ## Rate Limits 216 | 217 | ### Free Tier Limits 218 | - 60 requests per minute 219 | - 1000 requests per day 220 | 221 | ### Rate Limit Behavior 222 | - CLI auto-retries with exponential backoff 223 | - Message: `"quota will reset after Xs"` 224 | - Typical wait: 1-5 seconds 225 | 226 | ### Mitigation 227 | 1. Use `gemini-2.5-flash` for simple tasks 228 | 2. Batch operations into single prompts 229 | 3. Run long tasks in background 230 | 231 | ## Interactive Commands 232 | 233 | In interactive mode, these slash commands are available: 234 | 235 | | Command | Purpose | 236 | |---------|---------| 237 | | `/help` | Show available commands | 238 | | `/tools` | List available tools | 239 | | `/stats` | Show token usage | 240 | | `/compress` | Summarize context to save tokens | 241 | | `/restore` | Restore file checkpoints | 242 | | `/chat save ` | Save conversation | 243 | | `/chat resume ` | Resume conversation | 244 | | `/memory show` | Display GEMINI.md context | 245 | | `/memory refresh` | Reload context files | 246 | 247 | ## Piping & Scripting 248 | 249 | ### Pipe Input 250 | ```bash 251 | echo "What is 2+2?" | gemini -o text 252 | cat file.txt | gemini "summarize this" -o text 253 | ``` 254 | 255 | ### File Reference Syntax 256 | In prompts, reference files with `@`: 257 | ```bash 258 | gemini "Review @./src/main.js for bugs" -o text 259 | ``` 260 | 261 | ### Shell Command Execution 262 | In interactive mode, prefix with `!`: 263 | ``` 264 | > !git status 265 | ``` 266 | 267 | ## Keyboard Shortcuts (Interactive) 268 | 269 | | Shortcut | Function | 270 | |----------|----------| 271 | | `Ctrl+L` | Clear screen | 272 | | `Ctrl+V` | Paste from clipboard | 273 | | `Ctrl+Y` | Toggle YOLO mode | 274 | | `Ctrl+X` | Open in external editor | 275 | 276 | ## Troubleshooting 277 | 278 | ### Common Issues 279 | 280 | | Issue | Solution | 281 | |-------|----------| 282 | | "API key not found" | Set `GEMINI_API_KEY` env var | 283 | | "Rate limit exceeded" | Wait for auto-retry or use Flash | 284 | | "Context too large" | Use `.geminiignore` or be specific | 285 | | "Tool call failed" | Check JSON stats for details | 286 | 287 | ### Debug Mode 288 | ```bash 289 | gemini "prompt" --debug -o text 290 | ``` 291 | 292 | ### Error Reports 293 | Full error reports saved to: 294 | ``` 295 | /var/folders/.../gemini-client-error-*.json 296 | ``` 297 | -------------------------------------------------------------------------------- /templates.md: -------------------------------------------------------------------------------- 1 | # Gemini CLI Prompt Templates 2 | 3 | Reusable prompt templates for common operations. 4 | 5 | ## Code Generation 6 | 7 | ### Single-File Application 8 | ```bash 9 | gemini "Create a [description] with [features]. Include [requirements]. Output the complete file content." --yolo -o text 10 | ``` 11 | 12 | **Example:** 13 | ```bash 14 | gemini "Create a single-file HTML/CSS/JS calculator with: basic operations, history display, keyboard support, dark mode toggle, responsive design. Output the complete file content." --yolo -o text 15 | ``` 16 | 17 | ### Multi-File Project 18 | ```bash 19 | gemini "Create a [project type] with [stack]. Include [features]. Create all necessary files and make it runnable. Use modern best practices. START BUILDING NOW." --yolo -o text 20 | ``` 21 | 22 | **Example:** 23 | ```bash 24 | gemini "Create a REST API with Express, SQLite, and JWT auth. Include user CRUD, input validation, error handling. Create all necessary files and make it runnable. START BUILDING NOW." --yolo -o text 25 | ``` 26 | 27 | ### Component/Module 28 | ```bash 29 | gemini "Create a [component type] that [functionality]. Follow [standards]. Include [requirements]. Output the code." --yolo -o text 30 | ``` 31 | 32 | **Example:** 33 | ```bash 34 | gemini "Create a React hook useLocalStorage that syncs state with localStorage. Follow React 18 best practices. Include TypeScript types. Output the code." --yolo -o text 35 | ``` 36 | 37 | ## Code Review 38 | 39 | ### Comprehensive Review 40 | ```bash 41 | gemini "Review [file] and tell me: 42 | 1) What features it has 43 | 2) Any bugs or security issues 44 | 3) Suggestions for improvement 45 | 4) Code quality assessment" -o text 46 | ``` 47 | 48 | ### Security-Focused Review 49 | ```bash 50 | gemini "Review [file] for security vulnerabilities including: 51 | - XSS (cross-site scripting) 52 | - SQL injection 53 | - Command injection 54 | - Insecure data handling 55 | - Authentication issues 56 | Report findings with severity levels." -o text 57 | ``` 58 | 59 | ### Performance Review 60 | ```bash 61 | gemini "Analyze [file] for performance issues: 62 | - Inefficient algorithms 63 | - Memory leaks 64 | - Unnecessary re-renders 65 | - Blocking operations 66 | - Optimization opportunities 67 | Provide specific recommendations." -o text 68 | ``` 69 | 70 | ## Bug Fixing 71 | 72 | ### Fix Identified Bugs 73 | ```bash 74 | gemini "Fix these bugs in [file]: 75 | 1) [Bug description] 76 | 2) [Bug description] 77 | 3) [Bug description] 78 | Apply fixes now." --yolo -o text 79 | ``` 80 | 81 | ### Auto-Detect and Fix 82 | ```bash 83 | gemini "Analyze [file] for bugs, then fix all issues you find. Apply fixes immediately." --yolo -o text 84 | ``` 85 | 86 | ## Test Generation 87 | 88 | ### Unit Tests 89 | ```bash 90 | gemini "Generate [framework] unit tests for [file]. Cover: 91 | - All public functions 92 | - Edge cases 93 | - Error handling 94 | - [Specific areas] 95 | Output the complete test file." --yolo -o text 96 | ``` 97 | 98 | **Example:** 99 | ```bash 100 | gemini "Generate Jest unit tests for utils.js. Cover: 101 | - All exported functions 102 | - Edge cases (empty input, null, undefined) 103 | - Error handling 104 | - Boundary conditions 105 | Output the complete test file." --yolo -o text 106 | ``` 107 | 108 | ### Integration Tests 109 | ```bash 110 | gemini "Generate integration tests for [component/API]. Test: 111 | - Happy path scenarios 112 | - Error scenarios 113 | - Edge cases 114 | Use [framework]. Output complete test file." --yolo -o text 115 | ``` 116 | 117 | ## Documentation 118 | 119 | ### JSDoc/TSDoc 120 | ```bash 121 | gemini "Generate [JSDoc/TSDoc] documentation for all functions in [file]. Include: 122 | - Function descriptions 123 | - Parameter types and descriptions 124 | - Return types and descriptions 125 | - Usage examples 126 | Output as [format]." --yolo -o text 127 | ``` 128 | 129 | ### README Generation 130 | ```bash 131 | gemini "Generate a README.md for this project. Include: 132 | - Project description 133 | - Installation instructions 134 | - Usage examples 135 | - API reference 136 | - Contributing guidelines 137 | Use the codebase to gather accurate information." --yolo -o text 138 | ``` 139 | 140 | ### API Documentation 141 | ```bash 142 | gemini "Document all API endpoints in [file/directory]. Include: 143 | - HTTP method and path 144 | - Request parameters 145 | - Request body schema 146 | - Response schema 147 | - Example requests/responses 148 | Output in [Markdown/OpenAPI] format." --yolo -o text 149 | ``` 150 | 151 | ## Code Transformation 152 | 153 | ### Refactoring 154 | ```bash 155 | gemini "Refactor [file] to: 156 | - [Specific improvement] 157 | - [Specific improvement] 158 | Maintain all existing functionality. Apply changes now." --yolo -o text 159 | ``` 160 | 161 | ### Language Translation 162 | ```bash 163 | gemini "Translate [file] from [source language] to [target language]. Maintain: 164 | - Same functionality 165 | - Similar code structure 166 | - Idiomatic patterns for target language 167 | Output the translated code." --yolo -o text 168 | ``` 169 | 170 | ### Framework Migration 171 | ```bash 172 | gemini "Convert [file] from [old framework] to [new framework]. Maintain all functionality. Use [new framework] best practices. Output the converted code." --yolo -o text 173 | ``` 174 | 175 | ## Web Research 176 | 177 | ### Current Information 178 | ```bash 179 | gemini "What are the latest [topic] as of [date]? Use Google Search to find current information. Summarize key points." -o text 180 | ``` 181 | 182 | ### Library/API Research 183 | ```bash 184 | gemini "Research [library/API] and provide: 185 | - Latest version and changes 186 | - Best practices 187 | - Common patterns 188 | - Gotchas to avoid 189 | Use Google Search for current information." -o text 190 | ``` 191 | 192 | ### Comparison Research 193 | ```bash 194 | gemini "Compare [option A] vs [option B] for [use case]. Use Google Search for current benchmarks and community opinions. Provide recommendation." -o text 195 | ``` 196 | 197 | ## Architecture Analysis 198 | 199 | ### Project Analysis 200 | ```bash 201 | gemini "Use the codebase_investigator tool to analyze this project. Report on: 202 | - Overall architecture 203 | - Key dependencies 204 | - Component relationships 205 | - Potential issues" -o text 206 | ``` 207 | 208 | ### Dependency Analysis 209 | ```bash 210 | gemini "Analyze dependencies in this project: 211 | - Direct vs transitive 212 | - Outdated packages 213 | - Security vulnerabilities 214 | - Bundle size impact 215 | Use available tools to gather information." -o text 216 | ``` 217 | 218 | ## Specialized Tasks 219 | 220 | ### Git Commit Message 221 | ```bash 222 | gemini "Analyze staged changes and generate a commit message following conventional commits format. Be concise but descriptive." -o text 223 | ``` 224 | 225 | ### Code Explanation 226 | ```bash 227 | gemini "Explain what [file/function] does in detail: 228 | - Purpose and use case 229 | - How it works step by step 230 | - Key algorithms/patterns used 231 | - Dependencies and side effects" -o text 232 | ``` 233 | 234 | ### Error Diagnosis 235 | ```bash 236 | gemini "Diagnose this error: 237 | [error message] 238 | Context: [relevant context] 239 | Provide: 240 | - Root cause 241 | - Solution steps 242 | - Prevention tips" -o text 243 | ``` 244 | 245 | ## Template Variables 246 | 247 | Use these placeholders in templates: 248 | 249 | - `[file]` - File path or name 250 | - `[directory]` - Directory path 251 | - `[description]` - Brief description 252 | - `[features]` - List of features 253 | - `[requirements]` - Specific requirements 254 | - `[framework]` - Testing/UI framework 255 | - `[language]` - Programming language 256 | - `[format]` - Output format (markdown, JSON, etc.) 257 | - `[date]` - Date for time-sensitive queries 258 | - `[topic]` - Subject matter for research 259 | -------------------------------------------------------------------------------- /tools.md: -------------------------------------------------------------------------------- 1 | # Gemini CLI Built-in Tools 2 | 3 | Reference for Gemini's built-in tools and their capabilities. 4 | 5 | ## Unique Tools (Not in Claude Code) 6 | 7 | These tools are available only through Gemini CLI: 8 | 9 | ### google_web_search 10 | 11 | Performs web search using Google Search API. 12 | 13 | **Capabilities:** 14 | - Real-time internet search 15 | - Current information (news, releases, docs) 16 | - Grounded responses with sources 17 | 18 | **Usage:** 19 | ```bash 20 | gemini "What are the latest React 19 features? Use Google Search." -o text 21 | ``` 22 | 23 | **Best For:** 24 | - Current events and news 25 | - Latest library versions 26 | - Recent documentation updates 27 | - Community opinions and benchmarks 28 | 29 | **Example Queries:** 30 | - "What are the security vulnerabilities in lodash 4.x? Use Google Search." 31 | - "What's new in TypeScript 5.4? Use Google Search." 32 | - "Best practices for Next.js 14 app router in November 2025." 33 | 34 | --- 35 | 36 | ### codebase_investigator 37 | 38 | Specialized tool for deep codebase analysis. 39 | 40 | **Capabilities:** 41 | - Architectural mapping 42 | - Dependency analysis 43 | - Cross-file relationship detection 44 | - System-wide pattern identification 45 | 46 | **Usage:** 47 | ```bash 48 | gemini "Use the codebase_investigator tool to analyze this project" -o text 49 | ``` 50 | 51 | **Output Includes:** 52 | - Overall architecture description 53 | - Key file purposes 54 | - Component relationships 55 | - Dependency chains 56 | - Potential issues/inconsistencies 57 | 58 | **Best For:** 59 | - Onboarding to new codebases 60 | - Understanding legacy systems 61 | - Finding hidden dependencies 62 | - Architecture documentation 63 | 64 | **Example:** 65 | ```bash 66 | gemini "Use codebase_investigator to map the authentication flow in this project" -o text 67 | ``` 68 | 69 | --- 70 | 71 | ### save_memory 72 | 73 | Saves information to persistent long-term memory. 74 | 75 | **Capabilities:** 76 | - Cross-session persistence 77 | - Key-value storage 78 | - Recall in future sessions 79 | 80 | **Usage:** 81 | ```bash 82 | gemini "Remember that this project uses Zustand for state management. Save this to memory." -o text 83 | ``` 84 | 85 | **Best For:** 86 | - Project conventions 87 | - User preferences 88 | - Recurring context 89 | - Custom instructions 90 | 91 | --- 92 | 93 | ## Standard Tools 94 | 95 | These tools are similar to Claude Code's capabilities: 96 | 97 | ### list_directory 98 | 99 | Lists files and subdirectories in a path. 100 | 101 | **Parameters:** 102 | - `path`: Directory to list 103 | - `ignore`: Glob patterns to exclude 104 | 105 | **Example Output:** 106 | ``` 107 | src/ 108 | components/ 109 | utils/ 110 | index.js 111 | package.json 112 | README.md 113 | ``` 114 | 115 | --- 116 | 117 | ### read_file 118 | 119 | Reads file content with truncation for large files. 120 | 121 | **Supported Formats:** 122 | - Text files (all types) 123 | - Images (PNG, JPG, GIF, WEBP, SVG, BMP) 124 | - PDF documents 125 | 126 | **Parameters:** 127 | - `path`: File path 128 | - `offset`: Starting line (for large files) 129 | - `limit`: Number of lines 130 | 131 | **Large File Handling:** 132 | If file exceeds limit, output indicates truncation and provides instructions for reading more with offset/limit. 133 | 134 | --- 135 | 136 | ### search_file_content 137 | 138 | Fast content search powered by ripgrep. 139 | 140 | **Advantages over grep:** 141 | - Optimized performance 142 | - Automatic output limiting (max 20k matches) 143 | - Better pattern matching 144 | 145 | **Parameters:** 146 | - `pattern`: Regex pattern 147 | - `path`: Search root 148 | - Various ripgrep flags 149 | 150 | --- 151 | 152 | ### glob 153 | 154 | Pattern-based file finding. 155 | 156 | **Returns:** 157 | - Absolute paths 158 | - Sorted by modification time (newest first) 159 | 160 | **Example Patterns:** 161 | - `src/**/*.ts` - All TypeScript files in src 162 | - `**/*.test.js` - All test files 163 | - `**/README.md` - All READMEs 164 | 165 | --- 166 | 167 | ### web_fetch 168 | 169 | Fetches content from URLs. 170 | 171 | **Capabilities:** 172 | - HTTP/HTTPS URLs 173 | - Local addresses (localhost) 174 | - Up to 20 URLs per request 175 | 176 | **Usage:** 177 | ```bash 178 | gemini "Fetch and summarize https://example.com/docs" -o text 179 | ``` 180 | 181 | --- 182 | 183 | ### write_todos 184 | 185 | Internal task tracking. 186 | 187 | **Capabilities:** 188 | - Track subtasks for complex requests 189 | - Organize multi-step work 190 | - Prevent missed steps 191 | 192 | **Automatic Usage:** 193 | Gemini uses this internally for complex tasks. 194 | 195 | --- 196 | 197 | ## Tool Invocation 198 | 199 | ### Automatic Tool Selection 200 | 201 | Gemini automatically selects appropriate tools based on the prompt: 202 | 203 | | Prompt Type | Tool Selected | 204 | |-------------|---------------| 205 | | "What files are in src/" | list_directory | 206 | | "Find all TODO comments" | search_file_content | 207 | | "Read package.json" | read_file | 208 | | "Find all React components" | glob | 209 | | "What's new in Vue 4?" | google_web_search | 210 | | "Analyze this codebase" | codebase_investigator | 211 | 212 | ### Explicit Tool Requests 213 | 214 | You can explicitly request tools: 215 | 216 | ```bash 217 | gemini "Use the codebase_investigator tool to..." -o text 218 | gemini "Search the web for..." -o text 219 | gemini "Use glob to find all..." -o text 220 | ``` 221 | 222 | --- 223 | 224 | ## Tool Statistics in JSON Output 225 | 226 | When using `-o json`, tool usage is reported: 227 | 228 | ```json 229 | { 230 | "stats": { 231 | "tools": { 232 | "totalCalls": 3, 233 | "totalSuccess": 3, 234 | "totalFail": 0, 235 | "totalDurationMs": 5000, 236 | "totalDecisions": { 237 | "accept": 0, 238 | "reject": 0, 239 | "modify": 0, 240 | "auto_accept": 3 241 | }, 242 | "byName": { 243 | "google_web_search": { 244 | "count": 1, 245 | "success": 1, 246 | "fail": 0, 247 | "durationMs": 3000, 248 | "decisions": { 249 | "auto_accept": 1 250 | } 251 | }, 252 | "read_file": { 253 | "count": 2, 254 | "success": 2, 255 | "fail": 0, 256 | "durationMs": 2000, 257 | "decisions": { 258 | "auto_accept": 2 259 | } 260 | } 261 | } 262 | } 263 | } 264 | } 265 | ``` 266 | 267 | --- 268 | 269 | ## Comparison with Claude Code Tools 270 | 271 | | Capability | Claude Code | Gemini CLI | 272 | |------------|-------------|------------| 273 | | File listing | LS, Glob | list_directory, glob | 274 | | File reading | Read | read_file | 275 | | File writing | Write, Edit | write_file (in YOLO) | 276 | | Code search | Grep | search_file_content | 277 | | Web fetch | WebFetch | web_fetch | 278 | | Web search | WebSearch | **google_web_search** | 279 | | Architecture | Task (Explore) | **codebase_investigator** | 280 | | Memory | N/A | **save_memory** | 281 | | Task tracking | TodoWrite | write_todos | 282 | 283 | **Bold** = Gemini's unique advantage 284 | 285 | --- 286 | 287 | ## Tool Restrictions 288 | 289 | ### Using allowed-tools 290 | 291 | In settings or command line, restrict available tools: 292 | 293 | ```bash 294 | gemini --allowed-tools "read_file,glob" "Find config files" -o text 295 | ``` 296 | 297 | ### In Settings 298 | ```json 299 | { 300 | "security": { 301 | "allowedTools": ["read_file", "list_directory", "glob"] 302 | } 303 | } 304 | ``` 305 | 306 | --- 307 | 308 | ## Best Practices 309 | 310 | ### When to Use Specific Tools 311 | 312 | **google_web_search:** 313 | - Need current/recent information 314 | - Checking latest versions 315 | - Finding documentation updates 316 | - Community solutions to problems 317 | 318 | **codebase_investigator:** 319 | - New to a codebase 320 | - Understanding complex systems 321 | - Finding hidden dependencies 322 | - Creating documentation 323 | 324 | **save_memory:** 325 | - Recurring project context 326 | - User preferences 327 | - Custom conventions 328 | 329 | ### Tool Combination Patterns 330 | 331 | **Research → Implement:** 332 | ```bash 333 | gemini "Use Google Search to find best practices for [topic], then implement them" --yolo -o text 334 | ``` 335 | 336 | **Analyze → Report:** 337 | ```bash 338 | gemini "Use codebase_investigator to analyze the project, then write a summary report" --yolo -o text 339 | ``` 340 | 341 | **Search → Read → Modify:** 342 | ```bash 343 | gemini "Find all files using deprecated API, read them, and suggest updates" -o text 344 | ``` 345 | -------------------------------------------------------------------------------- /patterns.md: -------------------------------------------------------------------------------- 1 | # Gemini CLI Integration Patterns 2 | 3 | Advanced patterns for orchestrating Gemini CLI effectively from Claude Code. 4 | 5 | ## Pattern 1: Generate-Review-Fix Cycle 6 | 7 | The most reliable pattern for quality code generation. 8 | 9 | ```bash 10 | # Step 1: Generate code 11 | gemini "Create [code description]" --yolo -o text 12 | 13 | # Step 2: Have Gemini review its own work 14 | gemini "Review [generated file] for bugs and security issues" -o text 15 | 16 | # Step 3: Fix identified issues 17 | gemini "Fix these issues in [file]: [list from review]. Apply now." --yolo -o text 18 | ``` 19 | 20 | ### Why It Works 21 | - Different "mindset" for generation vs review 22 | - Self-correction catches common mistakes 23 | - Security vulnerabilities often caught in review phase 24 | 25 | ### Example 26 | ```bash 27 | # Generate 28 | gemini "Create a user authentication module with bcrypt and JWT" --yolo -o text 29 | 30 | # Review 31 | gemini "Review auth.js for security vulnerabilities" -o text 32 | # Output: "Found XSS risk, missing input validation, weak JWT secret" 33 | 34 | # Fix 35 | gemini "Fix in auth.js: XSS risk, add input validation, use env var for JWT secret. Apply now." --yolo -o text 36 | ``` 37 | 38 | ## Pattern 2: JSON Output for Programmatic Processing 39 | 40 | Use JSON output when you need to process results programmatically. 41 | 42 | ```bash 43 | gemini "[prompt]" -o json 2>&1 44 | ``` 45 | 46 | ### Parsing the Response 47 | 48 | ```javascript 49 | // In Node.js or with jq 50 | const result = JSON.parse(output); 51 | const content = result.response; 52 | const tokenUsage = result.stats.models["gemini-2.5-flash"].tokens.total; 53 | const toolCalls = result.stats.tools.byName; 54 | ``` 55 | 56 | ### Use Cases 57 | - Extracting specific data from responses 58 | - Monitoring token usage 59 | - Tracking tool call success/failure 60 | - Building automation pipelines 61 | 62 | ## Pattern 3: Background Execution 63 | 64 | For long-running tasks, execute in background and continue working. 65 | 66 | ```bash 67 | # Start in background 68 | gemini "[long task]" --yolo -o text 2>&1 & 69 | 70 | # Get process ID for later 71 | echo $! 72 | 73 | # Monitor output incrementally with BashOutput tool 74 | ``` 75 | 76 | ### When to Use 77 | - Code generation for large projects 78 | - Documentation generation 79 | - Running multiple Gemini tasks in parallel 80 | 81 | ### Parallel Execution 82 | ```bash 83 | # Run multiple tasks simultaneously 84 | gemini "Create frontend" --yolo -o text 2>&1 & 85 | gemini "Create backend" --yolo -o text 2>&1 & 86 | gemini "Create tests" --yolo -o text 2>&1 & 87 | ``` 88 | 89 | ## Pattern 4: Model Selection Strategy 90 | 91 | Choose the right model for the task. 92 | 93 | ### Decision Tree 94 | 95 | ``` 96 | Is the task complex (architecture, multi-file, deep analysis)? 97 | ├── Yes → Use default (Gemini 3 Pro) 98 | └── No → Is speed critical? 99 | ├── Yes → Use gemini-2.5-flash 100 | └── No → Is it trivial (formatting, simple query)? 101 | ├── Yes → Use gemini-2.5-flash-lite 102 | └── No → Use gemini-2.5-flash 103 | ``` 104 | 105 | ### Examples 106 | ```bash 107 | # Complex: Architecture analysis 108 | gemini "Analyze codebase architecture" -o text 109 | 110 | # Quick: Simple formatting 111 | gemini "Format this JSON" -m gemini-2.5-flash -o text 112 | 113 | # Trivial: One-liner 114 | gemini "What is 2+2?" -m gemini-2.5-flash -o text 115 | ``` 116 | 117 | ## Pattern 5: Rate Limit Handling 118 | 119 | Strategies for working within rate limits. 120 | 121 | ### Approach 1: Let Auto-Retry Handle It 122 | Default behavior - CLI retries automatically with backoff. 123 | 124 | ### Approach 2: Use Flash for Lower Priority 125 | ```bash 126 | # High priority: Use Pro 127 | gemini "[important task]" --yolo -o text 128 | 129 | # Lower priority: Use Flash (different quota) 130 | gemini "[less critical task]" -m gemini-2.5-flash -o text 131 | ``` 132 | 133 | ### Approach 3: Batch Operations 134 | Combine related operations into single prompts: 135 | ```bash 136 | # Instead of multiple calls: 137 | gemini "Create file A" --yolo 138 | gemini "Create file B" --yolo 139 | gemini "Create file C" --yolo 140 | 141 | # Single call: 142 | gemini "Create files A, B, and C with [specs]. Create all now." --yolo 143 | ``` 144 | 145 | ### Approach 4: Sequential with Delays 146 | For automated scripts, add delays: 147 | ```bash 148 | gemini "[task 1]" --yolo -o text 149 | sleep 2 150 | gemini "[task 2]" --yolo -o text 151 | ``` 152 | 153 | ## Pattern 6: Context Enrichment 154 | 155 | Provide rich context for better results. 156 | 157 | ### Using File References 158 | ```bash 159 | gemini "Based on @./package.json and @./src/index.js, suggest improvements" -o text 160 | ``` 161 | 162 | ### Using GEMINI.md 163 | Create project context that's automatically included: 164 | ```markdown 165 | # .gemini/GEMINI.md 166 | 167 | ## Project Overview 168 | This is a React app using TypeScript. 169 | 170 | ## Coding Standards 171 | - Use functional components 172 | - Prefer hooks over classes 173 | - All functions need JSDoc 174 | ``` 175 | 176 | ### Explicit Context in Prompt 177 | ```bash 178 | gemini "Given this context: 179 | - Project uses React 18 with TypeScript 180 | - State management: Zustand 181 | - Styling: Tailwind CSS 182 | 183 | Create a user profile component." --yolo -o text 184 | ``` 185 | 186 | ## Pattern 7: Validation Pipeline 187 | 188 | Always validate Gemini's output before using. 189 | 190 | ### Validation Steps 191 | 192 | 1. **Syntax Check** 193 | ```bash 194 | # For JavaScript 195 | node --check generated.js 196 | 197 | # For TypeScript 198 | tsc --noEmit generated.ts 199 | ``` 200 | 201 | 2. **Security Scan** 202 | - Check for innerHTML with user input (XSS) 203 | - Look for eval() or Function() calls 204 | - Verify input validation 205 | 206 | 3. **Functional Test** 207 | - Run any generated tests 208 | - Manual smoke test 209 | 210 | 4. **Style Check** 211 | ```bash 212 | eslint generated.js 213 | prettier --check generated.js 214 | ``` 215 | 216 | ### Automated Validation Pattern 217 | ```bash 218 | # Generate 219 | gemini "Create utility functions" --yolo -o text 220 | 221 | # Validate 222 | node --check utils.js && eslint utils.js && npm test 223 | ``` 224 | 225 | ## Pattern 8: Incremental Refinement 226 | 227 | Build complex outputs in stages. 228 | 229 | ```bash 230 | # Stage 1: Core structure 231 | gemini "Create basic Express server with routes for /api/users" --yolo -o text 232 | 233 | # Stage 2: Add feature 234 | gemini "Add authentication middleware to the Express server in server.js" --yolo -o text 235 | 236 | # Stage 3: Add another feature 237 | gemini "Add rate limiting to the Express server in server.js" --yolo -o text 238 | 239 | # Stage 4: Review all 240 | gemini "Review server.js for issues and optimize" -o text 241 | ``` 242 | 243 | ### Benefits 244 | - Easier to debug issues 245 | - Each stage validates before continuing 246 | - Clear audit trail 247 | 248 | ## Pattern 9: Cross-Validation with Claude 249 | 250 | Use both AIs for highest quality. 251 | 252 | ### Claude Generates, Gemini Reviews 253 | ```bash 254 | # 1. Claude writes code (using normal Claude Code tools) 255 | # 2. Gemini reviews 256 | gemini "Review this code for bugs and security issues: [paste code]" -o text 257 | ``` 258 | 259 | ### Gemini Generates, Claude Reviews 260 | ```bash 261 | # 1. Gemini generates 262 | gemini "Create [code]" --yolo -o text 263 | 264 | # 2. Claude reviews the output (in conversation) 265 | # "Review this code that Gemini generated..." 266 | ``` 267 | 268 | ### Different Perspectives 269 | - Claude: Strong on reasoning, following complex instructions 270 | - Gemini: Strong on current web knowledge, codebase investigation 271 | 272 | ## Pattern 10: Session Continuity 273 | 274 | Use sessions for multi-turn workflows. 275 | 276 | ```bash 277 | # Initial task 278 | gemini "Analyze this codebase architecture" -o text 279 | # Session saved automatically 280 | 281 | # List sessions 282 | gemini --list-sessions 283 | 284 | # Continue with follow-up 285 | echo "What patterns did you find?" | gemini -r 1 -o text 286 | 287 | # Further refinement 288 | echo "Focus on the authentication flow" | gemini -r 1 -o text 289 | ``` 290 | 291 | ### Use Cases 292 | - Iterative analysis 293 | - Building on previous context 294 | - Debugging sessions 295 | 296 | ## Anti-Patterns to Avoid 297 | 298 | ### Don't: Expect Immediate Execution 299 | YOLO mode doesn't prevent planning. Gemini may still present plans. 300 | 301 | **Do**: Use forceful language ("Apply now", "Start immediately") 302 | 303 | ### Don't: Ignore Rate Limits 304 | Hammering the API wastes time on retries. 305 | 306 | **Do**: Use appropriate models, batch operations 307 | 308 | ### Don't: Trust Output Blindly 309 | Gemini can make mistakes, especially with security. 310 | 311 | **Do**: Always validate generated code 312 | 313 | ### Don't: Over-Specify in Single Prompt 314 | Extremely long prompts can confuse the model. 315 | 316 | **Do**: Use incremental refinement for complex tasks 317 | 318 | ### Don't: Forget Context Limits 319 | Even with 1M tokens, context can overflow. 320 | 321 | **Do**: Use .geminiignore, be specific about files 322 | --------------------------------------------------------------------------------