Initial commit
This commit is contained in:
Zhongwei Li
306
skills/gemini/references/command-patterns.md
Normal file
306
skills/gemini/references/command-patterns.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# Gemini CLI Command Patterns
|
||||
|
||||
**Purpose**: Common command templates for Gemini CLI integration
|
||||
**Version**: v0.16.0+
|
||||
**Last Updated**: 2025-11-18
|
||||
|
||||
## Basic Invocation Patterns
|
||||
|
||||
### One-Shot Queries (Headless Mode)
|
||||
|
||||
```bash
|
||||
# Preferred syntax (positional prompt)
|
||||
gemini -m gemini-3-pro-preview "Explain the observer pattern in software design"
|
||||
|
||||
# Alternative (deprecated -p flag, still works)
|
||||
gemini -m gemini-3-pro-preview -p "Explain the observer pattern in software design"
|
||||
|
||||
# With stdin input
|
||||
echo "function add(a, b) { return a + b; }" | gemini -m gemini-3-pro-preview "Explain this code"
|
||||
```
|
||||
|
||||
### Model Selection
|
||||
|
||||
```bash
|
||||
# Use Gemini 3 Pro (default for complex reasoning)
|
||||
gemini -m gemini-3-pro-preview "Design a microservices architecture"
|
||||
|
||||
# Use Gemini 2.5 Pro (stable, general reasoning)
|
||||
gemini -m gemini-2.5-pro "Review this API design"
|
||||
|
||||
# Use Gemini 2.5 Flash (faster, code-focused)
|
||||
gemini -m gemini-2.5-flash "Refactor this function for performance"
|
||||
```
|
||||
|
||||
### Version-Based Model Selection
|
||||
|
||||
When user requests a specific version, map to the latest model in that family:
|
||||
|
||||
```bash
|
||||
# User says "use Gemini 3" or "use 3" → Latest 3.x Pro
|
||||
gemini -m gemini-3-pro-preview "Design a distributed caching system"
|
||||
|
||||
# User says "use Gemini 2.5" for general tasks → 2.5 Pro
|
||||
gemini -m gemini-2.5-pro "Explain the CAP theorem with examples"
|
||||
|
||||
# User says "use Gemini 2.5" for code editing → 2.5 Flash
|
||||
gemini -m gemini-2.5-flash "Refactor this module for readability"
|
||||
|
||||
# No version specified → Default to latest Pro
|
||||
gemini -m gemini-3-pro-preview "Research microservices best practices"
|
||||
```
|
||||
|
||||
**Fallback Strategy** (when primary model unavailable):
|
||||
|
||||
```bash
|
||||
# Try Gemini 3 Pro first
|
||||
gemini -m gemini-3-pro-preview "Complex reasoning task" 2>&1
|
||||
|
||||
# If quota exhausted, fallback to 2.5 Pro (general) or 2.5 Flash (code)
|
||||
if [ $? -ne 0 ]; then
|
||||
# For general reasoning
|
||||
gemini -m gemini-2.5-pro "Complex reasoning task"
|
||||
|
||||
# OR for code editing
|
||||
# gemini -m gemini-2.5-flash "Complex reasoning task"
|
||||
fi
|
||||
```
|
||||
|
||||
## Output Formatting
|
||||
|
||||
### Text Output (Default)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview "What is dependency injection?"
|
||||
```
|
||||
|
||||
### JSON Output (Programmatic)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview --output-format json "List top 5 design patterns"
|
||||
```
|
||||
|
||||
### Streaming JSON (Real-time)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview --output-format stream-json "Explain async/await in JavaScript"
|
||||
```
|
||||
|
||||
## Approval Modes & Security
|
||||
|
||||
### Default Mode (Prompt for all actions)
|
||||
|
||||
```bash
|
||||
# Explicit
|
||||
gemini -m gemini-3-pro-preview --approval-mode default "Refactor this code"
|
||||
|
||||
# Implicit (no flag = default)
|
||||
gemini -m gemini-3-pro-preview "Refactor this code"
|
||||
```
|
||||
|
||||
### Auto-Edit Mode (Auto-approve edit tools only)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview --approval-mode auto_edit "Fix bugs in this file"
|
||||
```
|
||||
|
||||
### YOLO Mode (Auto-approve all tools)
|
||||
|
||||
```bash
|
||||
# Long form
|
||||
gemini -m gemini-3-pro-preview --approval-mode yolo "Deploy to production"
|
||||
|
||||
# Short form
|
||||
gemini -m gemini-3-pro-preview -y "Deploy to production"
|
||||
```
|
||||
|
||||
## Sandbox Mode
|
||||
|
||||
### Enable Sandbox
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview -s "Run untrusted code analysis"
|
||||
```
|
||||
|
||||
### Disable Sandbox (Default)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview "Analyze trusted codebase"
|
||||
```
|
||||
|
||||
## Session Management
|
||||
|
||||
### List Sessions
|
||||
|
||||
```bash
|
||||
gemini --list-sessions
|
||||
```
|
||||
|
||||
### Resume Sessions
|
||||
|
||||
```bash
|
||||
# Resume most recent session
|
||||
gemini -r latest
|
||||
|
||||
# Resume specific session by index
|
||||
gemini -r 3
|
||||
|
||||
# Resume and add new prompt
|
||||
gemini -r latest "Continue from where we left off"
|
||||
```
|
||||
|
||||
### Delete Sessions
|
||||
|
||||
```bash
|
||||
gemini --delete-session 5
|
||||
```
|
||||
|
||||
## Extensions & MCP
|
||||
|
||||
### List Available Extensions
|
||||
|
||||
```bash
|
||||
gemini -l
|
||||
# or
|
||||
gemini --list-extensions
|
||||
```
|
||||
|
||||
### Use Specific Extensions
|
||||
|
||||
```bash
|
||||
gemini -e web_search,code_analysis "Research React best practices"
|
||||
```
|
||||
|
||||
### Use All Extensions (Default)
|
||||
|
||||
```bash
|
||||
gemini "Research React best practices"
|
||||
```
|
||||
|
||||
## Workspace Context
|
||||
|
||||
### Include Additional Directories
|
||||
|
||||
```bash
|
||||
gemini --include-directories ./lib,./tests "Analyze the full project"
|
||||
|
||||
# Or multiple flags
|
||||
gemini --include-directories ./lib --include-directories ./tests "Analyze project"
|
||||
```
|
||||
|
||||
## Combined Patterns
|
||||
|
||||
### Production-Safe Code Review
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-pro \
|
||||
--approval-mode default \
|
||||
--output-format json \
|
||||
"Review this pull request for security issues"
|
||||
```
|
||||
|
||||
### Fast Code Refactoring
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-flash \
|
||||
--approval-mode auto_edit \
|
||||
"Refactor these functions for better performance"
|
||||
```
|
||||
|
||||
### Research with Web Search
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview \
|
||||
-e web_search \
|
||||
--output-format text \
|
||||
"What are the latest trends in GraphQL?"
|
||||
```
|
||||
|
||||
### Sandbox Testing
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-pro \
|
||||
-s \
|
||||
--approval-mode default \
|
||||
"Test this suspicious code snippet"
|
||||
```
|
||||
|
||||
## Claude Code Integration Patterns
|
||||
|
||||
### Skill Invocation (via Claude)
|
||||
|
||||
```bash
|
||||
# Basic invocation from skill
|
||||
gemini -m gemini-3-pro-preview "Explain microservices"
|
||||
|
||||
# With explicit approval mode
|
||||
gemini -m gemini-2.5-pro --approval-mode auto_edit "Fix type errors"
|
||||
|
||||
# With JSON output for parsing
|
||||
gemini -m gemini-2.5-flash --output-format json "List API endpoints"
|
||||
```
|
||||
|
||||
### Error Handling Pattern
|
||||
|
||||
```bash
|
||||
# Check CLI availability
|
||||
if ! command -v gemini &> /dev/null; then
|
||||
echo "Error: Gemini CLI not installed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Execute with error capture
|
||||
gemini -m gemini-3-pro-preview "task" 2>&1 || echo "Gemini CLI failed"
|
||||
```
|
||||
|
||||
## Model Selection by Task Type
|
||||
|
||||
### Complex Reasoning (General)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview "Design system architecture"
|
||||
```
|
||||
|
||||
### Code Review & Analysis
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-pro "Review this pull request"
|
||||
```
|
||||
|
||||
### Fast Code Editing
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-flash "Fix syntax errors in this file"
|
||||
```
|
||||
|
||||
## Anti-Patterns (Avoid These)
|
||||
|
||||
```bash
|
||||
# ❌ Using -p flag (deprecated)
|
||||
gemini -p "prompt" # Will be removed in future
|
||||
|
||||
# ❌ Using -i for headless mode
|
||||
gemini -i "prompt" # This starts interactive mode, not one-shot
|
||||
|
||||
# ❌ Hardcoding model without fallback
|
||||
# Always have fallback logic when gemini-3-pro-preview unavailable
|
||||
|
||||
# ❌ Using YOLO mode without user confirmation
|
||||
# Always require explicit user approval for YOLO mode
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Prefer Positional Prompts**: Use `gemini "prompt"` instead of `gemini -p "prompt"`
|
||||
2. **Specify Model Explicitly**: Always use `-m` flag for predictable behavior
|
||||
3. **Use Appropriate Approval Mode**: Default for untrusted tasks, auto_edit for code editing
|
||||
4. **Enable Sandbox for Unknown Code**: Use `-s` when analyzing untrusted input
|
||||
5. **Format Output for Parsing**: Use `--output-format json` when processing results programmatically
|
||||
6. **Resume Sessions When Needed**: Use `-r latest` for multi-turn conversations
|
||||
7. **Validate CLI Availability**: Always check `command -v gemini` before invocation
|
||||
|
||||
## See Also
|
||||
|
||||
- `gemini-help.md` - Full CLI reference
|
||||
- `session-workflows.md` - Session continuation patterns
|
||||
- `model-selection.md` - Model selection guidance
|
||||
147
skills/gemini/references/gemini-help.md
Normal file
147
skills/gemini/references/gemini-help.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Gemini CLI Help Reference
|
||||
|
||||
**Version**: v0.16.0+
|
||||
**Source**: Output from `gemini --help`
|
||||
**Last Updated**: 2025-11-18
|
||||
|
||||
## Command Overview
|
||||
|
||||
```
|
||||
Usage: gemini [options] [command]
|
||||
|
||||
Gemini CLI - Launch an interactive CLI, use -p/--prompt for non-interactive mode
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
- `gemini [query..]` - Launch Gemini CLI (default)
|
||||
- `gemini mcp` - Manage MCP servers
|
||||
- `gemini extensions <command>` - Manage Gemini CLI extensions
|
||||
|
||||
## Positionals
|
||||
|
||||
- `query` - Positional prompt. Defaults to one-shot; use `-i`/`--prompt-interactive` for interactive mode
|
||||
|
||||
## Options
|
||||
|
||||
### Core Flags
|
||||
|
||||
- `-d, --debug` - Run in debug mode [boolean] [default: false]
|
||||
- `-m, --model` - Model to use [string]
|
||||
- `-p, --prompt` - Prompt text appended to stdin input [string]
|
||||
**⚠️ DEPRECATED**: Use positional prompt instead. This flag will be removed in a future version.
|
||||
- `-i, --prompt-interactive` - Execute prompt and continue in interactive mode [string]
|
||||
- `-s, --sandbox` - Run in sandbox [boolean]
|
||||
|
||||
### Approval & Security
|
||||
|
||||
- `-y, --yolo` - Automatically accept all actions (YOLO mode) [boolean] [default: false]
|
||||
- `--approval-mode` - Set approval mode [string]
|
||||
**Choices**: `default` (prompt for approval), `auto_edit` (auto-approve edit tools), `yolo` (auto-approve all tools)
|
||||
- `--allowed-tools` - Tools allowed to run without confirmation [array]
|
||||
|
||||
### Session Management
|
||||
|
||||
- `-r, --resume` - Resume previous session [string]
|
||||
Use `"latest"` for most recent or index number (e.g., `--resume 5`)
|
||||
- `--list-sessions` - List available sessions for current project and exit [boolean]
|
||||
- `--delete-session` - Delete session by index number [string]
|
||||
|
||||
### Extensions & MCP
|
||||
|
||||
- `-e, --extensions` - List of extensions to use [array]
|
||||
If not provided, all extensions are used
|
||||
- `-l, --list-extensions` - List all available extensions and exit [boolean]
|
||||
- `--allowed-mcp-server-names` - Allowed MCP server names [array]
|
||||
|
||||
### Workspace & Context
|
||||
|
||||
- `--include-directories` - Additional directories to include in workspace [array]
|
||||
Comma-separated or multiple `--include-directories` flags
|
||||
- `--screen-reader` - Enable screen reader mode for accessibility [boolean]
|
||||
|
||||
### Output
|
||||
|
||||
- `-o, --output-format` - Format of CLI output [string]
|
||||
**Choices**: `text`, `json`, `stream-json`
|
||||
|
||||
### Meta
|
||||
|
||||
- `-v, --version` - Show version number [boolean]
|
||||
- `-h, --help` - Show help [boolean]
|
||||
- `--experimental-acp` - Start agent in ACP mode [boolean]
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Headless/Non-Interactive Mode
|
||||
|
||||
```bash
|
||||
# Preferred: Positional prompt
|
||||
gemini -m gemini-3-pro-preview "Explain quicksort algorithm"
|
||||
|
||||
# Deprecated but still works: -p flag
|
||||
gemini -m gemini-3-pro-preview -p "Explain quicksort algorithm"
|
||||
|
||||
# With output formatting
|
||||
gemini -m gemini-3-pro-preview --output-format json "Analyze this code"
|
||||
|
||||
# With approval mode
|
||||
gemini -m gemini-3-pro-preview --approval-mode auto_edit "Refactor this function"
|
||||
```
|
||||
|
||||
### Session Management
|
||||
|
||||
```bash
|
||||
# List sessions
|
||||
gemini --list-sessions
|
||||
|
||||
# Resume latest session
|
||||
gemini -r latest
|
||||
|
||||
# Resume specific session by index
|
||||
gemini -r 5
|
||||
|
||||
# Delete session
|
||||
gemini --delete-session 3
|
||||
```
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
```bash
|
||||
# Start interactive session
|
||||
gemini
|
||||
|
||||
# Execute prompt then continue interactively
|
||||
gemini -i "Start by explaining React hooks"
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **Positional Prompts**: Preferred over `-p` flag as of v0.16.0
|
||||
2. **Deprecation Warning**: `-p/--prompt` flag marked for removal in future versions
|
||||
3. **Session Resume**: Fully supported via `-r/--resume` flag
|
||||
4. **Approval Modes**: Three levels (default, auto_edit, yolo)
|
||||
5. **Output Formats**: Text (default), JSON, or streaming JSON for programmatic use
|
||||
6. **MCP Integration**: Built-in support for Model Context Protocol servers
|
||||
7. **Extensions**: Plugin system for custom commands and functionality
|
||||
|
||||
## Session Index Format
|
||||
|
||||
Sessions are identified by:
|
||||
- `"latest"` keyword for most recent session
|
||||
- Integer index (e.g., `0`, `1`, `2`, etc.)
|
||||
- Retrieved via `--list-sessions` command
|
||||
|
||||
## Compatibility Notes
|
||||
|
||||
- **Minimum Version**: v0.16.0
|
||||
- **Breaking Changes in v0.16.0**:
|
||||
- `-p` flag deprecated in favor of positional prompts
|
||||
- Checkpointing moved to settings.json configuration
|
||||
- **Future Deprecations**: `-p/--prompt` flag will be removed
|
||||
|
||||
## See Also
|
||||
|
||||
- `command-patterns.md` - Common command templates
|
||||
- `session-workflows.md` - Multi-turn conversation patterns
|
||||
- `model-selection.md` - Model selection guidance
|
||||
313
skills/gemini/references/model-selection.md
Normal file
313
skills/gemini/references/model-selection.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# Gemini Model Selection Guide
|
||||
|
||||
**Purpose**: Guide for selecting the right Gemini model for your task
|
||||
**Version**: v0.16.0+
|
||||
**Last Updated**: 2025-11-18
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task Type | Recommended Model | Reason |
|
||||
|-----------|------------------|---------|
|
||||
| Complex reasoning, architecture design | `gemini-3-pro-preview` | Latest capabilities, best for hard problems |
|
||||
| General reasoning, code review | `gemini-2.5-pro` | Stable, reliable, 1M context |
|
||||
| Code editing, refactoring | `gemini-2.5-flash` | Faster, optimized for code |
|
||||
| When Gemini 3 quota exhausted | `gemini-2.5-pro` → `gemini-2.5-flash` | Graceful degradation |
|
||||
|
||||
## Version-Based Model Mapping
|
||||
|
||||
### Concept
|
||||
|
||||
When users mention a version number (e.g., "use Gemini 3"), map to the latest model in that family for future-proofing.
|
||||
|
||||
### Current Mappings (as of Nov 2025)
|
||||
|
||||
| User Request | Maps To | Actual Model ID | Status | Notes |
|
||||
|--------------|---------|-----------------|--------|-------|
|
||||
| "Gemini 3" or "use 3" | Latest 3.x Pro | `gemini-3-pro-preview` | Preview | Requires preview access |
|
||||
| "Gemini 2.5" (general) | 2.5 Pro | `gemini-2.5-pro` | Stable | 1M tokens context |
|
||||
| "Gemini 2.5" (code editing) | 2.5 Flash | `gemini-2.5-flash` | Stable | Optimized for speed |
|
||||
| No version specified | Latest Pro | `gemini-3-pro-preview` | Preview | **DEFAULT** |
|
||||
|
||||
### Future-Proofing Strategy
|
||||
|
||||
```
|
||||
User says "3" → Plugin maps to latest_3x_pro
|
||||
Currently: gemini-3-pro-preview
|
||||
Future: gemini-3-pro (when stable)
|
||||
gemini-3.1-pro (when released)
|
||||
|
||||
User says "2.5" → Plugin maps based on task:
|
||||
General: gemini-2.5-pro
|
||||
Code: gemini-2.5-flash
|
||||
```
|
||||
|
||||
**Maintenance**: Update mapping table when new models release
|
||||
|
||||
## Model Family Overview
|
||||
|
||||
### Gemini 3 Family (Latest - Preview)
|
||||
|
||||
**gemini-3-pro-preview**
|
||||
- **Status**: Preview (requires access)
|
||||
- **Context**: 1M tokens
|
||||
- **Strengths**: Cutting-edge reasoning, complex problem-solving
|
||||
- **Use Cases**: System architecture, complex algorithms, research
|
||||
- **Access**: Google AI Ultra subscribers, paid API keys, or waitlist
|
||||
- **Availability**: May be quota-limited on free tier
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview "Design a distributed caching system"
|
||||
```
|
||||
|
||||
### Gemini 2.5 Family (Stable)
|
||||
|
||||
**gemini-2.5-pro**
|
||||
- **Status**: Stable, production-ready
|
||||
- **Context**: 1M tokens
|
||||
- **Strengths**: General reasoning, balanced performance
|
||||
- **Use Cases**: Code review, technical writing, general assistance
|
||||
- **Access**: Free tier (60 req/min, 1000 req/day)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-pro "Review this API design for best practices"
|
||||
```
|
||||
|
||||
**gemini-2.5-flash**
|
||||
- **Status**: Stable, production-ready
|
||||
- **Context**: Unknown (likely lower than Pro)
|
||||
- **Strengths**: Speed, code generation/editing
|
||||
- **Use Cases**: Quick refactoring, syntax fixes, fast iterations
|
||||
- **Access**: Free tier (60 req/min, 1000 req/day)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-flash "Refactor this function for better performance"
|
||||
```
|
||||
|
||||
**gemini-2.5-flash-lite** (if available)
|
||||
- **Status**: Stable (check CLI for availability)
|
||||
- **Strengths**: Highest throughput, lowest cost
|
||||
- **Use Cases**: High-volume simple tasks
|
||||
- **Note**: May have reduced capabilities
|
||||
|
||||
## Task-Based Selection
|
||||
|
||||
### By Task Complexity
|
||||
|
||||
```
|
||||
High Complexity (System Design, Architecture)
|
||||
↓
|
||||
gemini-3-pro-preview
|
||||
↓ (if unavailable)
|
||||
gemini-2.5-pro
|
||||
|
||||
Medium Complexity (Code Review, Analysis)
|
||||
↓
|
||||
gemini-2.5-pro
|
||||
|
||||
Low Complexity (Code Editing, Refactoring)
|
||||
↓
|
||||
gemini-2.5-flash
|
||||
```
|
||||
|
||||
### By Task Type
|
||||
|
||||
**Research & Design**
|
||||
- Primary: `gemini-3-pro-preview`
|
||||
- Fallback: `gemini-2.5-pro`
|
||||
- Example: "Design a microservices architecture"
|
||||
|
||||
**Code Review & Analysis**
|
||||
- Primary: `gemini-2.5-pro`
|
||||
- Fallback: `gemini-2.5-flash`
|
||||
- Example: "Review this pull request for bugs"
|
||||
|
||||
**Code Generation & Editing**
|
||||
- Primary: `gemini-2.5-flash`
|
||||
- Fallback: `gemini-2.5-pro`
|
||||
- Example: "Refactor this code for readability"
|
||||
|
||||
**General Questions**
|
||||
- Primary: `gemini-3-pro-preview`
|
||||
- Fallback: `gemini-2.5-pro`
|
||||
- Example: "Explain the CAP theorem"
|
||||
|
||||
## Selection Decision Tree
|
||||
|
||||
```
|
||||
START: User makes request
|
||||
│
|
||||
├─> User specifies model? ─────────────────┐
|
||||
│ (e.g., -m gemini-2.5-pro) │
|
||||
│ YES ──> Use specified model ──> END │
|
||||
│ NO ───> Continue │
|
||||
│ │
|
||||
├─> User mentions version? ────────────────┤
|
||||
│ (e.g., "use 3" or "use 2.5") │
|
||||
│ YES ──> Map to latest in family ──> END│
|
||||
│ NO ───> Continue │
|
||||
│ │
|
||||
├─> Classify task type: │
|
||||
│ - Complex reasoning? ──> gemini-3-pro-preview
|
||||
│ - Code editing? ──> gemini-2.5-flash │
|
||||
│ - General? ──> gemini-2.5-pro │
|
||||
│ │
|
||||
└─> Apply fallback if primary unavailable │
|
||||
(quota exhausted, access denied) │
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Fallback Strategy
|
||||
|
||||
### When Gemini 3 Pro Unavailable
|
||||
|
||||
**Reason**: Quota exhausted, access denied, or service issue
|
||||
|
||||
**Fallback Logic**:
|
||||
```
|
||||
gemini-3-pro-preview unavailable
|
||||
│
|
||||
├─> Task type: General reasoning
|
||||
│ └─> Use: gemini-2.5-pro
|
||||
│
|
||||
└─> Task type: Code editing
|
||||
└─> Use: gemini-2.5-flash
|
||||
```
|
||||
|
||||
**Implementation Pattern**:
|
||||
```bash
|
||||
# Try Gemini 3 Pro first
|
||||
gemini -m gemini-3-pro-preview "Design system" 2>&1
|
||||
|
||||
# If fails with quota/access error, retry with fallback
|
||||
if [ $? -ne 0 ]; then
|
||||
gemini -m gemini-2.5-pro "Design system"
|
||||
fi
|
||||
```
|
||||
|
||||
## Free Tier Considerations
|
||||
|
||||
### Rate Limits (OAuth Free Tier)
|
||||
|
||||
- **60 requests per minute**
|
||||
- **1,000 requests per day**
|
||||
- **Context**: 1M tokens with Gemini 2.5 Pro
|
||||
|
||||
### Quota Management
|
||||
|
||||
**Gemini 3 Pro (Preview)**:
|
||||
- May have stricter quotas
|
||||
- May auto-switch to lower tier when exhausted
|
||||
- Monitor for 429 (rate limit) or 403 (quota exceeded) errors
|
||||
|
||||
**Gemini 2.5 Models**:
|
||||
- More generous free tier quotas
|
||||
- Better availability
|
||||
- Recommended for high-volume usage
|
||||
|
||||
### Cost Optimization
|
||||
|
||||
```
|
||||
High volume, simple tasks → gemini-2.5-flash (fastest, cheapest)
|
||||
Moderate volume, general → gemini-2.5-pro (balanced)
|
||||
Low volume, complex → gemini-3-pro-preview (best quality)
|
||||
```
|
||||
|
||||
## Model Capabilities Comparison
|
||||
|
||||
| Capability | Gemini 3 Pro | Gemini 2.5 Pro | Gemini 2.5 Flash |
|
||||
|-----------|--------------|----------------|------------------|
|
||||
| Reasoning | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
|
||||
| Code Generation | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||||
| Speed | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||||
| Context Window | 1M tokens | 1M tokens | Unknown |
|
||||
| Stability | Preview | Stable | Stable |
|
||||
| Free Tier Access | Limited | Yes | Yes |
|
||||
|
||||
## Access Requirements
|
||||
|
||||
### Gemini 3 Pro Access
|
||||
|
||||
**Preview Features Required**:
|
||||
1. Update Gemini CLI to v0.16.x+
|
||||
2. Enable Preview Features in CLI settings
|
||||
3. Have one of:
|
||||
- Google AI Ultra subscription
|
||||
- Paid Gemini API key
|
||||
- Vertex API key with Gemini 3 access
|
||||
- Waitlist approval (free tier users)
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview "test" 2>&1
|
||||
|
||||
# Success: Model responds
|
||||
# Failure: 404 "model not found" or 403 "access denied"
|
||||
```
|
||||
|
||||
### Gemini 2.5 Access
|
||||
|
||||
**Always Available** (free tier):
|
||||
- `gemini-2.5-pro`
|
||||
- `gemini-2.5-flash`
|
||||
|
||||
No special access required.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Default to Latest Pro**: Start with `gemini-3-pro-preview` when available
|
||||
2. **Implement Graceful Fallback**: Always have 2.5 fallback logic
|
||||
3. **Match Model to Task**: Don't use Gemini 3 for simple edits
|
||||
4. **Monitor Quotas**: Track rate limits and switch models proactively
|
||||
5. **Update Mapping Table**: Review quarterly for new model releases
|
||||
6. **Test Access**: Verify Gemini 3 Pro access before defaulting to it
|
||||
7. **Use Explicit Model Selection**: Specify `-m` rather than relying on CLI defaults
|
||||
|
||||
## Updating This Guide
|
||||
|
||||
When new models are released:
|
||||
|
||||
1. Update "Current Mappings" table
|
||||
2. Add new model to "Model Family Overview"
|
||||
3. Update "Model Capabilities Comparison"
|
||||
4. Revise fallback logic if needed
|
||||
5. Update examples with new model IDs
|
||||
6. Test all command patterns
|
||||
7. Update "Last Updated" date
|
||||
|
||||
## Example Selection Scenarios
|
||||
|
||||
### Scenario 1: System Architecture Design
|
||||
|
||||
**Task**: "Design a scalable payment processing system"
|
||||
**Selection**: `gemini-3-pro-preview` (complex reasoning)
|
||||
**Fallback**: `gemini-2.5-pro` (if quota exhausted)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview "Design a scalable payment processing system"
|
||||
```
|
||||
|
||||
### Scenario 2: Quick Code Fix
|
||||
|
||||
**Task**: "Fix the syntax error in this JavaScript"
|
||||
**Selection**: `gemini-2.5-flash` (simple, fast)
|
||||
**Fallback**: `gemini-2.5-pro` (if Flash unavailable)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-flash "Fix the syntax error in this code"
|
||||
```
|
||||
|
||||
### Scenario 3: Pull Request Review
|
||||
|
||||
**Task**: "Review this pull request for best practices"
|
||||
**Selection**: `gemini-2.5-pro` (balanced, thorough)
|
||||
**Fallback**: `gemini-2.5-flash` (if quota tight)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-pro "Review this pull request"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- `gemini-help.md` - Full CLI reference
|
||||
- `command-patterns.md` - Common command templates
|
||||
- `session-workflows.md` - Session continuation patterns
|
||||
309
skills/gemini/references/session-workflows.md
Normal file
309
skills/gemini/references/session-workflows.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# Gemini CLI Session Workflows
|
||||
|
||||
**Purpose**: Guide for session management and multi-turn conversations
|
||||
**Version**: v0.16.0+
|
||||
**Last Updated**: 2025-11-18
|
||||
|
||||
**Note**: Session management features documented here are available in Gemini CLI v0.16.0+ but may not be directly accessible through Claude Code's headless integration. See limitations section below.
|
||||
|
||||
## Overview
|
||||
|
||||
Gemini CLI supports session persistence for multi-turn conversations, allowing you to resume previous interactions and build on context across multiple invocations.
|
||||
|
||||
## Session Basics
|
||||
|
||||
### What is a Session?
|
||||
|
||||
A session is a conversation thread with Gemini that:
|
||||
- Maintains conversation history
|
||||
- Preserves context across turns
|
||||
- Can be resumed later
|
||||
- Is stored locally in `~/.gemini/`
|
||||
|
||||
### Session Lifecycle
|
||||
|
||||
```
|
||||
Create → Use → Pause → Resume → Complete → Archive/Delete
|
||||
```
|
||||
|
||||
## Session Management Commands
|
||||
|
||||
### List Available Sessions
|
||||
|
||||
```bash
|
||||
gemini --list-sessions
|
||||
```
|
||||
|
||||
**Example Output**:
|
||||
```
|
||||
Available sessions:
|
||||
0: "test non-interactive mode" (5 minutes ago)
|
||||
1: "architecture design discussion" (1 hour ago)
|
||||
2: "code review session" (yesterday)
|
||||
```
|
||||
|
||||
### Resume a Session
|
||||
|
||||
```bash
|
||||
# Resume most recent session
|
||||
gemini -r latest
|
||||
|
||||
# Resume specific session by index
|
||||
gemini -r 0
|
||||
gemini -r 1
|
||||
gemini -r 2
|
||||
|
||||
# Resume and add new prompt
|
||||
gemini -r latest "Continue our discussion about microservices"
|
||||
```
|
||||
|
||||
### Delete a Session
|
||||
|
||||
```bash
|
||||
# Delete session by index
|
||||
gemini --delete-session 0
|
||||
|
||||
# Delete after listing
|
||||
gemini --list-sessions
|
||||
gemini --delete-session 2
|
||||
```
|
||||
|
||||
## Session Workflows
|
||||
|
||||
### Workflow 1: Iterative Development
|
||||
|
||||
**Scenario**: Building a feature across multiple sessions
|
||||
|
||||
```bash
|
||||
# Session 1: Initial design
|
||||
gemini -m gemini-3-pro-preview "Design a user authentication system"
|
||||
# ... conversation happens ...
|
||||
|
||||
# Later: Resume to implement
|
||||
gemini -r latest "Now help me implement the login component"
|
||||
|
||||
# Even later: Review and refine
|
||||
gemini -r latest "Review the implementation for security issues"
|
||||
```
|
||||
|
||||
### Workflow 2: Research Continuation
|
||||
|
||||
**Scenario**: Deep research across multiple timeframes
|
||||
|
||||
```bash
|
||||
# Day 1: Start research
|
||||
gemini -m gemini-3-pro-preview -e web_search "Research GraphQL best practices"
|
||||
|
||||
# Day 2: Continue research
|
||||
gemini -r latest "Now compare GraphQL with REST for our use case"
|
||||
|
||||
# Day 3: Make decision
|
||||
gemini -r latest "Based on our research, recommend the best approach"
|
||||
```
|
||||
|
||||
### Workflow 3: Code Review Marathon
|
||||
|
||||
**Scenario**: Reviewing multiple files in sequence
|
||||
|
||||
```bash
|
||||
# Start with first file
|
||||
gemini -m gemini-2.5-pro "Review this authentication module"
|
||||
|
||||
# Resume for next file (context preserved)
|
||||
gemini -r latest "Now review the authorization module"
|
||||
|
||||
# Continue pattern
|
||||
gemini -r latest "Review the session management module"
|
||||
```
|
||||
|
||||
### Workflow 4: Collaborative Debugging
|
||||
|
||||
**Scenario**: Debugging complex issues over time
|
||||
|
||||
```bash
|
||||
# Initial investigation
|
||||
gemini -m gemini-2.5-pro "Help debug this memory leak"
|
||||
|
||||
# After implementing first fix
|
||||
gemini -r latest "The leak still occurs. Here's the new log output..."
|
||||
|
||||
# Final resolution
|
||||
gemini -r latest "Confirmed fixed! Summarize what we found"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Use Sessions
|
||||
|
||||
✅ **Good Use Cases**:
|
||||
- Complex multi-step tasks
|
||||
- Iterative design and implementation
|
||||
- Long-running research projects
|
||||
- Code review across multiple files
|
||||
- Debugging sessions spanning multiple attempts
|
||||
|
||||
❌ **Poor Use Cases**:
|
||||
- Quick one-off queries
|
||||
- Unrelated tasks
|
||||
- Simple factual questions
|
||||
- When context doesn't matter
|
||||
|
||||
### Session Management Tips
|
||||
|
||||
1. **Name Sessions Meaningfully**: Use descriptive names for easy identification
|
||||
2. **Clean Up Regularly**: Delete completed sessions to reduce clutter
|
||||
3. **Use Latest Wisely**: `gemini -r latest` is convenient but verify you're resuming the right session
|
||||
4. **Context Limits**: Very long sessions may hit context window limits
|
||||
5. **Explicit Resume**: When in doubt, use numeric index rather than `latest`
|
||||
|
||||
### Session Organization
|
||||
|
||||
```bash
|
||||
# Pattern: One session per feature/task
|
||||
# Session 0: "auth-implementation"
|
||||
# Session 1: "payment-integration"
|
||||
# Session 2: "performance-optimization"
|
||||
|
||||
# Check which session you need
|
||||
gemini --list-sessions
|
||||
|
||||
# Resume the right one
|
||||
gemini -r 1 # payment-integration
|
||||
```
|
||||
|
||||
## Session Storage
|
||||
|
||||
### Location
|
||||
|
||||
Sessions are stored in:
|
||||
```
|
||||
~/.gemini/
|
||||
├── sessions/
|
||||
│ ├── session-0.json
|
||||
│ ├── session-1.json
|
||||
│ └── session-2.json
|
||||
└── settings.json
|
||||
```
|
||||
|
||||
### Privacy & Security
|
||||
|
||||
- Sessions stored locally only
|
||||
- No automatic cloud sync
|
||||
- Contains conversation history
|
||||
- May include sensitive code/data
|
||||
- Should be included in `.gitignore`
|
||||
|
||||
## Interactive vs Non-Interactive Sessions
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
```bash
|
||||
# Start interactive session
|
||||
gemini
|
||||
|
||||
# Session automatically created
|
||||
# Type /chat save mytag to save with tag
|
||||
# Type /chat resume mytag to resume later
|
||||
```
|
||||
|
||||
### Non-Interactive Mode (Headless)
|
||||
|
||||
```bash
|
||||
# Sessions work with -r flag
|
||||
gemini -r latest "New prompt here"
|
||||
|
||||
# But creating NEW sessions requires prompt-interactive
|
||||
gemini -i "Start session with this prompt"
|
||||
```
|
||||
|
||||
## Limitations in Claude Code Integration
|
||||
|
||||
⚠️ **Important**: Claude Code's bash environment is non-interactive/headless, which means:
|
||||
|
||||
1. **No Interactive Session Commands**: Commands like `/chat save` and `/chat resume` don't work in headless mode
|
||||
2. **Resume Flag May Work**: The `-r` flag SHOULD work for resuming, but hasn't been tested in headless context
|
||||
3. **Session Creation**: New sessions created automatically on first invocation
|
||||
4. **Session Persistence**: Sessions persist across Claude Code skill invocations if using same working directory
|
||||
|
||||
### Workaround for Claude Code
|
||||
|
||||
Since full session management may not be available in headless mode, consider:
|
||||
- Using one-shot queries for each invocation
|
||||
- Maintaining conversation context at the plugin level (if needed)
|
||||
- Documenting session management as manual user workflow outside Claude Code
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Session Branching
|
||||
|
||||
```bash
|
||||
# Main session
|
||||
gemini -r 0 "Implement approach A"
|
||||
|
||||
# Try alternative without affecting main session
|
||||
gemini "Try approach B instead" # New session
|
||||
|
||||
# Return to main session
|
||||
gemini -r 0 "Continue with approach A"
|
||||
```
|
||||
|
||||
### Session Cleanup Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# cleanup-old-sessions.sh
|
||||
|
||||
# List sessions
|
||||
gemini --list-sessions
|
||||
|
||||
# Delete sessions older than 7 days (manual inspection required)
|
||||
# No automated deletion to prevent data loss
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Session Not Found
|
||||
|
||||
```bash
|
||||
$ gemini -r 5
|
||||
Error: Session 5 not found
|
||||
|
||||
# Solution: List sessions first
|
||||
$ gemini --list-sessions
|
||||
# Use valid index
|
||||
```
|
||||
|
||||
### Lost Session Context
|
||||
|
||||
```bash
|
||||
# If session seems to have lost context:
|
||||
# 1. Verify you're resuming correct session
|
||||
gemini --list-sessions
|
||||
|
||||
# 2. Resume with summary prompt
|
||||
gemini -r 2 "Summarize what we discussed so far"
|
||||
|
||||
# 3. If context truly lost, start fresh
|
||||
gemini "Let's restart our discussion about..."
|
||||
```
|
||||
|
||||
### Session Conflicts
|
||||
|
||||
```bash
|
||||
# If multiple sessions seem to interfere:
|
||||
# 1. Check current sessions
|
||||
gemini --list-sessions
|
||||
|
||||
# 2. Delete unused sessions
|
||||
gemini --delete-session 1
|
||||
gemini --delete-session 3
|
||||
|
||||
# 3. Start fresh with clear naming
|
||||
gemini "New session: payment gateway integration"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- `gemini-help.md` - Full CLI reference
|
||||
- `command-patterns.md` - Common command templates
|
||||
- `model-selection.md` - Model selection guidance
|
||||
Reference in New Issue
Block a user