Initial commit
This commit is contained in:
Zhongwei Li
14
.claude-plugin/plugin.json
Normal file
14
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "gemini",
|
||||
"description": "Google Gemini CLI integration for Claude Code. Provides access to Gemini AI models with intelligent model selection, session continuation, and safe defaults.",
|
||||
"version": "1.1.0",
|
||||
"author": {
|
||||
"name": "0xasun"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"agents": [
|
||||
"./agents"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# gemini
|
||||
|
||||
Google Gemini CLI integration for Claude Code. Provides access to Gemini AI models with intelligent model selection, session continuation, and safe defaults.
|
||||
12
agents/gemini-agent.md
Normal file
12
agents/gemini-agent.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
name: gemini-agent
|
||||
description: Invoke Google Gemini for research, explanations, reasoning tasks, and web search integration
|
||||
when-to-use: Use when user requests Gemini, needs research help, or asks for explanations and reasoning
|
||||
model: inherit
|
||||
---
|
||||
|
||||
You are a routing agent for the Gemini skill.
|
||||
|
||||
When invoked, use the Skill tool to invoke the "gemini" skill.
|
||||
Pass the user's request directly to the skill without modification.
|
||||
Let the skill handle all task execution.
|
||||
65
plugin.lock.json
Normal file
65
plugin.lock.json
Normal file
@@ -0,0 +1,65 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:Lucklyric/cc-dev-tools:plugins/gemini",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "79b87bde6fb224c7f021d5ed228455e1a9379bda",
|
||||
"treeHash": "9d03d2199263a733361d2aab8fdcf9b8128e1306c6cce995d286282f473b3dc9",
|
||||
"generatedAt": "2025-11-28T10:12:03.041556Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "gemini",
|
||||
"description": "Google Gemini CLI integration for Claude Code. Provides access to Gemini AI models with intelligent model selection, session continuation, and safe defaults.",
|
||||
"version": "1.1.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "af0e6a370697c68e01c649923b62ecda9ad54ca82d7a38757fbd763103f9769d"
|
||||
},
|
||||
{
|
||||
"path": "agents/gemini-agent.md",
|
||||
"sha256": "51835b3716e715d81a2c0bb570c645af898b0e21548891ca80f485ec1e93c9aa"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "831a30d05c66c555591bca52a8aeec060c68dc960970464a3b8f867a8f16ad43"
|
||||
},
|
||||
{
|
||||
"path": "skills/gemini/SKILL.md",
|
||||
"sha256": "f54c3fad8ff9e0eb4e5b5f3ab713a25324d6b79f3290244bb619a8d0d1b35838"
|
||||
},
|
||||
{
|
||||
"path": "skills/gemini/references/model-selection.md",
|
||||
"sha256": "e40d6b7668e9e5d1f4b18003995b680669d5ca45d5e0c06bd20d00da05926a5a"
|
||||
},
|
||||
{
|
||||
"path": "skills/gemini/references/session-workflows.md",
|
||||
"sha256": "a22db3506191f34167a733f2e23905163705371e3c900b0fd8f7f0d9565a3af4"
|
||||
},
|
||||
{
|
||||
"path": "skills/gemini/references/gemini-help.md",
|
||||
"sha256": "150d1144994d8e05e4578aa9886fc6f112552525288fffb7eeb693e433f9932a"
|
||||
},
|
||||
{
|
||||
"path": "skills/gemini/references/command-patterns.md",
|
||||
"sha256": "57a46c3cc21f2043cc4b64803a5c1f2dcefa4378d5d2e6997dd9437142dd5903"
|
||||
}
|
||||
],
|
||||
"dirSha256": "9d03d2199263a733361d2aab8fdcf9b8128e1306c6cce995d286282f473b3dc9"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
400
skills/gemini/SKILL.md
Normal file
400
skills/gemini/SKILL.md
Normal file
@@ -0,0 +1,400 @@
|
||||
---
|
||||
name: gemini
|
||||
version: 1.0.0
|
||||
description: Invoke Google Gemini CLI for complex reasoning tasks, research, and AI assistance. This skill should be invoked when users explicitly mention "Gemini", request Google's AI models, need advanced reasoning capabilities, or want to continue previous Gemini conversations. Automatically triggers on Gemini-related requests and supports session continuation for iterative development.
|
||||
---
|
||||
|
||||
# Gemini: Google AI Assistant for Claude Code
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL: Positional Prompts Preferred
|
||||
|
||||
**PREFERRED**: Use positional prompts for Gemini CLI invocations (future-proof).
|
||||
|
||||
**DEPRECATED**: `-p` flag still works but will be removed in future versions.
|
||||
|
||||
**Examples:**
|
||||
- `gemini -m gemini-3-pro-preview "prompt"` (PREFERRED - positional)
|
||||
- `gemini -m gemini-3-pro-preview -p "prompt"` (DEPRECATED - will be removed)
|
||||
- `gemini -r latest` (CORRECT - session resume)
|
||||
|
||||
**Why?** Gemini CLI v0.16.0 deprecated the `-p` flag in favor of positional prompts. While `-p` still works, it will be removed in a future version. Use positional prompts for forward compatibility.
|
||||
|
||||
---
|
||||
|
||||
## IMPORTANT: Preview Features & OAuth Free Tier
|
||||
|
||||
**For OAuth free tier users in headless mode:**
|
||||
|
||||
When `previewFeatures: true` in `~/.gemini/settings.json`, the CLI routes ALL requests to Gemini 3 Pro (even `-m gemini-2.5-pro`). Since free tier doesn't have Gemini 3 access, this causes 404 errors.
|
||||
|
||||
**Solution**: Disable preview features for reliable headless operation:
|
||||
```json
|
||||
// ~/.gemini/settings.json
|
||||
{
|
||||
"general": {
|
||||
"previewFeatures": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Plugin Behavior**: This skill automatically falls back to `gemini-2.5-flash` when encountering 404 errors. Flash always works with OAuth free tier.
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
This skill should be invoked when:
|
||||
- User explicitly mentions "Gemini" or requests Gemini assistance
|
||||
- User needs Google's AI models for reasoning, research, or analysis
|
||||
- User requests complex problem-solving or architectural design
|
||||
- User needs research capabilities with web search integration
|
||||
- User wants to continue a previous Gemini conversation
|
||||
- User needs an alternative to Codex or Claude for specific tasks
|
||||
|
||||
## How It Works
|
||||
|
||||
### Detecting New Gemini Requests
|
||||
|
||||
When a user makes a request that falls into one of the above categories, determine the task type:
|
||||
|
||||
**General Reasoning Tasks** (architecture, design, reviews, research):
|
||||
- Use model: `gemini-3-pro-preview` (latest, highest reasoning)
|
||||
- Fallback: `gemini-2.5-pro` (stable, general reasoning)
|
||||
- Example requests: "Design a distributed cache", "Research GraphQL best practices", "Explain CQRS pattern"
|
||||
|
||||
**Code Editing Tasks** (file modifications, refactoring):
|
||||
- Use model: `gemini-2.5-flash` (optimized for speed and code)
|
||||
- Fallback: `gemini-2.5-pro` (if Flash unavailable)
|
||||
- Example requests: "Refactor this function", "Fix syntax errors", "Optimize this code"
|
||||
|
||||
### Bash CLI Command Structure
|
||||
|
||||
**IMPORTANT**: Gemini CLI works differently from Codex - no `exec` subcommand needed. Use positional prompts directly.
|
||||
|
||||
#### For General Reasoning Tasks (Default)
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro-preview \
|
||||
--approval-mode auto_edit \
|
||||
--output-format text \
|
||||
"Design a microservices architecture for e-commerce"
|
||||
```
|
||||
|
||||
#### For Code Editing Tasks
|
||||
|
||||
```bash
|
||||
gemini -m gemini-2.5-flash \
|
||||
--approval-mode auto_edit \
|
||||
--output-format text \
|
||||
"Refactor this function for better performance"
|
||||
```
|
||||
|
||||
#### For Session Continuation
|
||||
|
||||
```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 our discussion about caching strategies"
|
||||
```
|
||||
|
||||
**Why positional prompts?**
|
||||
- Simpler, more direct syntax
|
||||
- Future-proof (recommended by Gemini CLI)
|
||||
- Works in non-TTY environments (like Claude Code's bash)
|
||||
- No separate `exec` command needed
|
||||
|
||||
### Model Selection Logic
|
||||
|
||||
**Use `gemini-3-pro-preview` (default) when:**
|
||||
- Designing architecture or system design
|
||||
- Conducting research or analysis
|
||||
- Explaining complex concepts
|
||||
- Planning implementation strategies
|
||||
- General problem-solving and advanced reasoning
|
||||
- User explicitly requests "Gemini 3" or "use 3"
|
||||
|
||||
**Use `gemini-2.5-pro` when:**
|
||||
- Gemini 3 Pro unavailable or quota exhausted
|
||||
- Stable, production-ready tasks
|
||||
- General reasoning with proven reliability
|
||||
- User explicitly requests "Gemini 2.5" or "use 2.5"
|
||||
|
||||
**Use `gemini-2.5-flash` when:**
|
||||
- Code editing or refactoring tasks
|
||||
- Fast iterations needed
|
||||
- Simple, quick responses
|
||||
- Gemini 3 Pro quota concerns
|
||||
|
||||
### Version-Based Model Mapping
|
||||
|
||||
When users mention a version number, map to the latest model in that family:
|
||||
|
||||
| User Request | Maps To | Actual Model ID |
|
||||
|--------------|---------|-----------------|
|
||||
| "use 3" / "Gemini 3" | Latest 3.x Pro | `gemini-3-pro-preview` |
|
||||
| "use 2.5" (general) | 2.5 Pro | `gemini-2.5-pro` |
|
||||
| "use 2.5" (code editing) | 2.5 Flash | `gemini-2.5-flash` |
|
||||
| No version specified | Latest Pro | `gemini-3-pro-preview` |
|
||||
|
||||
**See**: `references/model-selection.md` for detailed model selection guidance and decision tree.
|
||||
|
||||
### Default Configuration
|
||||
|
||||
All Gemini invocations use these defaults unless user specifies otherwise:
|
||||
|
||||
| Parameter | Default Value | CLI Flag | Notes |
|
||||
|-----------|---------------|----------|-------|
|
||||
| Model (general) | `gemini-3-pro-preview` | `-m gemini-3-pro-preview` | Tries first, falls back to Flash |
|
||||
| Model (fallback) | `gemini-2.5-flash` | `-m gemini-2.5-flash` | Always works on free tier |
|
||||
| Model (code editing) | `gemini-2.5-flash` | `-m gemini-2.5-flash` | Optimized for code |
|
||||
| Approval Mode | `auto_edit` | `--approval-mode auto_edit` | Auto-approve edit tools only |
|
||||
| Sandbox | `false` (disabled) | No flag | Sandbox disabled by default |
|
||||
| Output Format | `text` | No flag | Human-readable text output |
|
||||
| Web Search | Enabled when appropriate | `-e web_search` (if needed) | Context-dependent |
|
||||
|
||||
**Rationale for Defaults:**
|
||||
- **Gemini 3 Pro → Flash Fallback**: Tries latest model first, automatically falls back to Flash (which always works on OAuth free tier)
|
||||
- **auto_edit mode**: Balances safety (prompts for destructive actions) with efficiency (auto-approves edits)
|
||||
- **No sandbox**: Claude Code environment assumed trusted
|
||||
- **Text output**: Default for human consumption (use `--output-format json` for parsing)
|
||||
|
||||
**Note**: If you have `previewFeatures: true` in settings, disable it for reliable headless operation (see warning above).
|
||||
|
||||
### Error Handling
|
||||
|
||||
The skill handles these common errors gracefully:
|
||||
|
||||
#### CLI Not Installed
|
||||
|
||||
**Error**: `command not found: gemini`
|
||||
|
||||
**Message**: "Gemini CLI not installed. Install from: https://github.com/google-gemini/gemini-cli"
|
||||
|
||||
**Action**: User must install Gemini CLI before using this skill
|
||||
|
||||
#### Authentication Required
|
||||
|
||||
**Error**: Output contains "auth" or "authentication"
|
||||
|
||||
**Message**: "Authentication required. Run: `gemini login` to authenticate with your Google account"
|
||||
|
||||
**Action**: User must authenticate via OAuth or API key
|
||||
|
||||
#### Rate Limit Exceeded
|
||||
|
||||
**Error**: Output contains "quota" or "rate limit" or status 429
|
||||
|
||||
**Message**: "Rate limit exceeded (60 req/min, 1000 req/day free tier). Retry in X seconds or upgrade account."
|
||||
|
||||
**Action**: Wait for rate limit reset or upgrade to paid tier
|
||||
|
||||
#### Model Unavailable
|
||||
|
||||
**Error**: Output contains "model not found" or "404" or status 403
|
||||
|
||||
**Message**: "Model unavailable. Trying fallback model..."
|
||||
|
||||
**Action**: Automatically retry with fallback:
|
||||
- `gemini-3-pro-preview` unavailable → try `gemini-2.5-pro`
|
||||
- `gemini-2.5-pro` unavailable → try `gemini-2.5-flash`
|
||||
|
||||
#### Session Not Found
|
||||
|
||||
**Error**: Using `-r` flag but session doesn't exist
|
||||
|
||||
**Message**: "Session not found. Use `gemini --list-sessions` to see available sessions."
|
||||
|
||||
**Action**: User should list sessions or start new session
|
||||
|
||||
#### Gemini 3 Pro Access Denied
|
||||
|
||||
**Error**: Status 403 or "preview access required"
|
||||
|
||||
**Message**: "Gemini 3 Pro requires preview access. Enable Preview Features in settings or use `gemini-2.5-pro` instead."
|
||||
|
||||
**Action**: Either enable preview features, get API key, or use 2.5 models
|
||||
|
||||
**See**: `references/gemini-help.md` for complete CLI reference and troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Invocation (General Reasoning)
|
||||
|
||||
```bash
|
||||
# Design system architecture
|
||||
gemini -m gemini-3-pro-preview "Design a scalable payment processing system"
|
||||
|
||||
# Research with web search
|
||||
gemini -m gemini-3-pro-preview -e web_search "Research latest React 19 features"
|
||||
|
||||
# Explain complex concept
|
||||
gemini -m gemini-2.5-pro "Explain the CAP theorem with real-world examples"
|
||||
```
|
||||
|
||||
### Code Editing Tasks
|
||||
|
||||
```bash
|
||||
# Fast refactoring
|
||||
gemini -m gemini-2.5-flash "Refactor this function for better readability"
|
||||
|
||||
# Fix syntax errors
|
||||
gemini -m gemini-2.5-flash "Fix the syntax errors in this JavaScript code"
|
||||
|
||||
# Optimize performance
|
||||
gemini -m gemini-2.5-flash "Optimize this database query for better performance"
|
||||
```
|
||||
|
||||
### Session Management
|
||||
|
||||
```bash
|
||||
# Start a session (automatic)
|
||||
gemini -m gemini-3-pro-preview "Design an authentication system"
|
||||
|
||||
# List available sessions
|
||||
gemini --list-sessions
|
||||
|
||||
# Resume most recent
|
||||
gemini -r latest
|
||||
|
||||
# Resume specific session
|
||||
gemini -r 3
|
||||
|
||||
# Continue with new prompt
|
||||
gemini -r latest "Now help me implement the login flow"
|
||||
```
|
||||
|
||||
### With Output Formatting
|
||||
|
||||
```bash
|
||||
# JSON output for parsing
|
||||
gemini -m gemini-2.5-pro --output-format json "List top 5 design patterns"
|
||||
|
||||
# Streaming JSON for real-time
|
||||
gemini -m gemini-2.5-pro --output-format stream-json "Explain async patterns"
|
||||
```
|
||||
|
||||
### Approval Modes
|
||||
|
||||
```bash
|
||||
# Default mode (prompt for all)
|
||||
gemini -m gemini-2.5-pro --approval-mode default "Review this code"
|
||||
|
||||
# Auto-edit (auto-approve edits only)
|
||||
gemini -m gemini-2.5-pro --approval-mode auto_edit "Refactor this module"
|
||||
|
||||
# YOLO mode (auto-approve ALL - use with caution)
|
||||
gemini -m gemini-2.5-pro --approval-mode yolo "Deploy to production"
|
||||
```
|
||||
|
||||
### Sandbox Mode
|
||||
|
||||
```bash
|
||||
# Enable sandbox for untrusted code
|
||||
gemini -m gemini-2.5-pro -s "Analyze this suspicious code snippet"
|
||||
|
||||
# Disabled by default (trusted environment)
|
||||
gemini -m gemini-2.5-pro "Review this internal codebase"
|
||||
```
|
||||
|
||||
### Extensions & MCP Integration
|
||||
|
||||
Gemini CLI supports extensions and Model Context Protocol (MCP) servers for enhanced functionality.
|
||||
|
||||
```bash
|
||||
# List available extensions
|
||||
gemini --list-extensions
|
||||
|
||||
# Use specific extensions (web search, code analysis, etc.)
|
||||
gemini -m gemini-3-pro-preview -e web_search "Research React 19 features"
|
||||
|
||||
# Use all extensions (default)
|
||||
gemini -m gemini-3-pro-preview "Design system architecture"
|
||||
```
|
||||
|
||||
**Note**: This plugin does not implement custom extensions or MCP servers. Users can configure extensions and MCP servers through the Gemini CLI's standard configuration in `~/.gemini/settings.json`. Extensions are enabled by default when appropriate for the task.
|
||||
|
||||
---
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
For detailed information, see the references directory:
|
||||
|
||||
- **`references/gemini-help.md`** - Complete Gemini CLI help output and flag reference
|
||||
- **`references/command-patterns.md`** - Common command templates organized by use case
|
||||
- **`references/session-workflows.md`** - Multi-turn conversation patterns and best practices
|
||||
- **`references/model-selection.md`** - Model selection decision tree and version mapping
|
||||
|
||||
---
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
1. **Always Specify Model**: Use `-m` flag explicitly for predictable behavior
|
||||
2. **Use Positional Prompts**: Prefer `gemini "prompt"` over deprecated `-p` flag
|
||||
3. **Enable Web Search When Needed**: Add `-e web_search` for research tasks
|
||||
4. **Resume Sessions for Complex Tasks**: Use `-r latest` for multi-turn conversations
|
||||
5. **Start with Gemini 3 Pro**: Default to `gemini-3-pro-preview`, fallback to 2.5 models
|
||||
6. **Use Appropriate Approval Mode**: `auto_edit` for code, `default` for untrusted tasks
|
||||
7. **Monitor Rate Limits**: 60 req/min, 1000 req/day on free tier
|
||||
8. **Check CLI Availability**: Validate `command -v gemini` before invocation
|
||||
|
||||
---
|
||||
|
||||
## Differences from Codex
|
||||
|
||||
| Feature | Codex CLI | Gemini CLI |
|
||||
|---------|-----------|------------|
|
||||
| Invocation | `codex exec "prompt"` | `gemini "prompt"` |
|
||||
| Subcommand | Required (`exec`) | Not needed |
|
||||
| Positional Prompts | Not supported | Preferred |
|
||||
| Session Resume | `codex exec resume --last` | `gemini -r latest` |
|
||||
| Models | GPT-5.1, GPT-5.1-Codex | Gemini 3 Pro, 2.5 Pro/Flash |
|
||||
| Provider | OpenAI (via Codex) | Google |
|
||||
|
||||
---
|
||||
|
||||
## When to Use Gemini vs Codex vs Claude
|
||||
|
||||
**Use Gemini when:**
|
||||
- You need Google's latest models
|
||||
- Research with web search is important
|
||||
- You prefer Google's AI capabilities
|
||||
- Codex is unavailable or rate-limited
|
||||
- Task benefits from Gemini's strengths
|
||||
|
||||
**Use Codex when:**
|
||||
- You need GPT-5.1's reasoning capabilities
|
||||
- Task requires high-reasoning model
|
||||
- Code editing with specific Codex optimizations
|
||||
- You're already using Codex workflow
|
||||
|
||||
**Use Claude (native) when:**
|
||||
- Simple queries within Claude Code's capabilities
|
||||
- No external AI needed
|
||||
- Quick responses preferred
|
||||
- Task doesn't require specialized models
|
||||
|
||||
---
|
||||
|
||||
## Version Compatibility
|
||||
|
||||
- **Minimum Gemini CLI**: v0.16.0
|
||||
- **Recommended**: v0.16.x stable (latest)
|
||||
- **Preview/Nightly**: Not required but available
|
||||
|
||||
**Breaking Changes in v0.16.0:**
|
||||
- `-p` flag deprecated (use positional prompts)
|
||||
- Checkpointing moved to settings.json
|
||||
- Session management via `-r` flag standard
|
||||
|
||||
---
|
||||
|
||||
For questions or issues, consult `references/gemini-help.md` or run `gemini --help`.
|
||||
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