gemini-executor 0.1.0

package/docs/architecture.md

@@ -0,0 +1,261 @@
+# Gemini CLI Integration Architecture
+
+## Overview
+
+This project integrates Google's Gemini CLI into Claude Code, enabling Claude to leverage Gemini's capabilities for specific tasks while maintaining Claude's strengths in code manipulation and project understanding.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Claude Code                        │
+│                                                      │
+│  ┌────────────────┐         ┌──────────────────┐  │
+│  │  User Request  │────────▶│   Task Router    │  │
+│  └────────────────┘         └──────────────────┘  │
+│                                     │               │
+│                    ┌────────────────┴───────────┐  │
+│                    │                            │  │
+│            ┌───────▼────────┐         ┌────────▼──────────┐
+│            │  Claude Agent  │         │  Gemini SubAgent  │
+│            │                │         │                   │
+│            │ • Code Editing │         │ • Complex Logic   │
+│            │ • File Ops     │         │ • Data Analysis   │
+│            │ • Git Ops      │         │ • Creative Tasks  │
+│            └────────────────┘         └─────────┬─────────┘
+│                                                  │
+│                                       ┌──────────▼─────────┐
+│                                       │   Gemini CLI       │
+│                                       │                    │
+│                                       │  gemini [options]  │
+│                                       └────────────────────┘
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### 1. Gemini SubAgent (`agents/gemini-agent.md`)
+
+A specialized agent that can be invoked via the Task tool with `subagent_type='gemini'`.
+
+**Purpose:**
+- Delegate complex reasoning tasks to Gemini
+- Leverage Gemini's strengths in creative problem-solving
+- Handle tasks requiring different reasoning approaches
+
+**Key Features:**
+- Automatic prompt construction
+- Output format handling (text/json)
+- Error handling and retry logic
+- Session management support
+
+**When to Use:**
+- Complex algorithm design
+- Data analysis and interpretation
+- Creative content generation
+- Alternative perspectives on problems
+- Tasks benefiting from Gemini's specific capabilities
+
+### 2. Gemini Skill (`skills/gemini/skill.md`)
+
+A user-invocable skill accessible via `/gemini` command.
+
+**Purpose:**
+- Quick access to Gemini from the command line
+- Interactive mode for iterative problem-solving
+- Direct user control over Gemini interactions
+
+**Key Features:**
+- Simple syntax: `/gemini <query>`
+- Support for interactive mode
+- Model selection
+- YOLO mode for automation
+
+**When to Use:**
+- User wants direct Gemini interaction
+- Quick queries and clarifications
+- Experimenting with different models
+- When Claude suggests consulting Gemini
+
+## Design Principles
+
+### 1. Complementary Strengths
+
+**Claude excels at:**
+- Code editing and refactoring
+- File system operations
+- Git operations
+- Understanding existing codebases
+- Following strict patterns and conventions
+
+**Gemini excels at:**
+- Creative problem-solving
+- Complex logical reasoning
+- Data analysis and interpretation
+- Explaining concepts in different ways
+- Exploring alternative approaches
+
+### 2. Seamless Integration
+
+The integration should feel natural:
+- Claude decides when to delegate to Gemini
+- Results are automatically integrated into Claude's workflow
+- Users can explicitly request Gemini via `/gemini`
+- Clear attribution of which AI generated what
+
+### 3. Flexible Invocation
+
+**Programmatic (SubAgent):**
+```typescript
+// Claude internally decides to use Gemini
+Task({
+  subagent_type: 'gemini',
+  prompt: 'Design an efficient algorithm for...',
+  description: 'Algorithm design with Gemini'
+})
+```
+
+**User-Driven (Skill):**
+```bash
+/gemini How should I structure my database schema for...
+/gemini -m gemini-2.0-flash-thinking-exp Explain the trade-offs...
+```
+
+## Integration Patterns
+
+### Pattern 1: Claude Plans, Gemini Designs
+
+```
+User: "Build a recommendation engine"
+  ↓
+Claude: Analyzes codebase, identifies requirements
+  ↓
+Claude → Gemini: "Design recommendation algorithm considering..."
+  ↓
+Gemini: Returns algorithm design
+  ↓
+Claude: Implements design in code
+```
+
+### Pattern 2: Iterative Refinement
+
+```
+User: "Optimize this SQL query"
+  ↓
+Claude: Analyzes current query
+  ↓
+Claude → Gemini: "Suggest optimizations for this query..."
+  ↓
+Gemini: Returns optimization suggestions
+  ↓
+Claude: Applies optimizations
+  ↓
+Claude: Runs tests and validates
+```
+
+### Pattern 3: Direct User Consultation
+
+```
+User: "/gemini What's the best approach for caching in microservices?"
+  ↓
+Gemini: Explains various caching strategies
+  ↓
+User: Discusses with Claude which to implement
+  ↓
+Claude: Implements chosen strategy
+```
+
+## Technical Implementation
+
+### Gemini CLI Invocation
+
+The system uses the installed Gemini CLI (`/opt/homebrew/bin/gemini`) with various modes:
+
+**One-shot mode:**
+```bash
+gemini "Design a caching strategy for..."
+```
+
+**Interactive mode:**
+```bash
+gemini -i "Let's design an API structure..."
+# Continues interactively
+```
+
+**JSON output:**
+```bash
+gemini -o json "Analyze this data structure..."
+```
+
+**Specific model:**
+```bash
+gemini -m gemini-2.0-flash-thinking-exp "Complex reasoning task..."
+```
+
+### Output Processing
+
+1. **Text output:** Direct integration into conversation
+2. **JSON output:** Structured data for programmatic processing
+3. **Stream JSON:** Real-time updates for long-running tasks
+
+### Error Handling
+
+- Graceful fallback if Gemini CLI unavailable
+- Timeout handling for long-running requests
+- Clear error messages to user
+- Retry logic for transient failures
+
+## Security Considerations
+
+1. **Input Sanitization:**
+   - Validate all inputs before passing to Gemini CLI
+   - Escape shell special characters
+   - Prevent command injection
+
+2. **Output Validation:**
+   - Parse and validate Gemini responses
+   - Sanitize before code generation
+   - Review before executing suggested commands
+
+3. **API Key Management:**
+   - Gemini CLI handles authentication
+   - No API keys stored in code
+   - Uses user's configured credentials
+
+## Performance Considerations
+
+1. **Caching:**
+   - Cache frequent queries
+   - Store session results
+   - Reuse previous Gemini insights
+
+2. **Parallel Execution:**
+   - Run Gemini tasks in background when possible
+   - Don't block Claude's other operations
+   - Use appropriate timeouts
+
+3. **Resource Management:**
+   - Monitor Gemini CLI process
+   - Clean up stale sessions
+   - Limit concurrent Gemini calls
+
+## Future Enhancements
+
+1. **Advanced Features:**
+   - Multi-turn Gemini conversations
+   - Vision capabilities for screenshots
+   - Code review collaboration (Claude + Gemini)
+
+2. **Configuration:**
+   - Per-project Gemini settings
+   - Custom prompts and templates
+   - Model selection preferences
+
+3. **Analytics:**
+   - Track Gemini usage
+   - Measure effectiveness
+   - Optimize delegation patterns
+
+## Examples
+
+See `skills/gemini/examples.md` for detailed usage examples.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "gemini-executor",
+  "version": "0.1.0",
+  "description": "Integration layer combining Google's Gemini CLI with Claude Code for complementary AI collaboration",
+  "main": "dist/agents/gemini-executor/index.js",
+  "types": "dist/agents/gemini-executor/index.d.ts",
+  "author": "mokasz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mokasz/gemini-executor.git"
+  },
+  "keywords": [
+    "gemini",
+    "claude",
+    "ai",
+    "cli",
+    "integration",
+    "multimodal",
+    "agent",
+    "claude-code",
+    "gemini-cli"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --ext .ts,.js",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "skills",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/gemini/skill.md

@@ -0,0 +1,362 @@
+# Gemini Skill
+
+User-invocable skill for direct interaction with Google's Gemini CLI from Claude Code.
+
+## Command Syntax
+
+```bash
+/gemini [options] <query>
+```
+
+## Basic Usage
+
+### Simple Query
+
+```bash
+/gemini Explain how async/await works in JavaScript
+```
+
+### With Specific Model
+
+```bash
+/gemini -m gemini-2.0-flash-thinking-exp Design a caching strategy for high-traffic API
+```
+
+### JSON Output
+
+```bash
+/gemini -o json Extract UI components from this design image
+```
+
+### Interactive Mode
+
+```bash
+/gemini -i Let's brainstorm ideas for improving code architecture
+```
+
+## Options
+
+| Option | Alias | Description | Example |
+|--------|-------|-------------|---------|
+| `--model <name>` | `-m` | Specify model to use | `-m gemini-2.0-flash` |
+| `--output <format>` | `-o` | Output format (text, json, stream-json) | `-o json` |
+| `--interactive` | `-i` | Enable interactive mode | `-i` |
+| `--files <paths>` | `-f` | Include file references | `-f ./src/index.ts` |
+| `--help` | `-h` | Show help message | `-h` |
+
+## Available Models
+
+- `gemini-2.0-flash` (default) - Fast, balanced performance
+- `gemini-2.0-flash-thinking-exp` - Advanced reasoning capabilities
+- `gemini-pro` - Enhanced capabilities for complex tasks
+
+## When to Use This Skill
+
+### Automatic Triggers
+
+This skill is automatically suggested when:
+
+1. **Multimodal Files**: User mentions image, PDF, audio, or video files
+2. **Large Context**: User requests analysis of entire project or large codebase
+3. **Explicit Request**: User says "use Gemini", "ask Gemini", or "/gemini"
+
+### Manual Invocation
+
+Invoke manually for:
+
+- Quick questions and clarifications
+- Alternative perspectives on problems
+- Creative brainstorming
+- Data analysis and interpretation
+- Experimenting with different models
+
+## Examples
+
+### Example 1: Code Review
+
+```bash
+/gemini Review this code for security vulnerabilities and suggest improvements
+```
+
+### Example 2: Architecture Analysis
+
+```bash
+/gemini -m gemini-2.0-flash-thinking-exp Analyze this project structure and suggest architectural improvements
+```
+
+### Example 3: UI Design Analysis
+
+```bash
+/gemini -f ./designs/mockup.png Extract all UI components and their specifications from this design
+```
+
+### Example 4: Data Analysis
+
+```bash
+/gemini -o json Analyze this dataset and identify trends ./data/metrics.csv
+```
+
+### Example 5: Interactive Problem Solving
+
+```bash
+/gemini -i I need help designing a scalable authentication system
+```
+
+## Workflow
+
+### 1. Intent Recognition
+
+When you invoke `/gemini`, Claude:
+- Parses your command and options
+- Validates file paths and inputs
+- Detects multimodal content
+
+### 2. Task Delegation
+
+Claude delegates to the gemini-executor SubAgent:
+```
+User → /gemini command
+    → Claude parses and validates
+        → Task tool with subagent_type='gemini-executor'
+            → Gemini CLI execution
+                → Result returned to Claude
+                    → Claude formats and presents to user
+```
+
+### 3. Result Presentation
+
+Claude presents results in a user-friendly format:
+- Summary of key points
+- Full Gemini output (expandable)
+- Suggested next actions
+- Related code snippets (if applicable)
+
+## Integration with Claude
+
+### Complementary Workflow
+
+```
+1. User: "Analyze this UI design mockup.png"
+2. Claude: [Detects image file, suggests /gemini skill]
+3. Gemini: [Analyzes image, extracts components]
+4. Claude: [Receives analysis, implements React components]
+5. Result: Working UI implementation based on design
+```
+
+### Context Isolation
+
+Gemini's lengthy outputs are processed separately:
+
+**Without isolation:**
+```
+Gemini output (5000 lines) → Main conversation
+→ Context overflow
+→ Subsequent responses affected
+```
+
+**With isolation:**
+```
+Gemini output (5000 lines) → SubAgent processing
+→ Summary (50 lines) → Main conversation
+→ Context preserved
+→ Details available on demand
+```
+
+## Output Formats
+
+### Text (Default)
+
+Plain text response from Gemini:
+
+```bash
+/gemini Explain dependency injection
+
+# Returns formatted text explanation
+```
+
+### JSON
+
+Structured data output:
+
+```bash
+/gemini -o json List the main components in this architecture
+
+# Returns parsed JSON:
+{
+  "components": [
+    {"name": "API Gateway", "type": "service"},
+    {"name": "Auth Service", "type": "microservice"}
+  ]
+}
+```
+
+### Stream JSON
+
+Real-time updates for long-running tasks:
+
+```bash
+/gemini -o stream-json Analyze entire codebase for patterns
+
+# Returns streaming JSON with progress updates
+```
+
+## Security Considerations
+
+### Automatic Checks
+
+The skill automatically:
+- ✅ Validates file paths
+- ✅ Detects sensitive files (.env, credentials, etc.)
+- ✅ Sanitizes user inputs
+- ✅ Prevents command injection
+- ✅ Warns about potential security issues
+
+### User Confirmations
+
+You'll be asked to confirm when:
+- Processing sensitive files
+- Accessing large numbers of files
+- Using experimental features
+
+## Limitations
+
+### File Size Limits
+
+- **Images**: max 20MB
+- **PDFs/Audio/Video**: max 100MB
+- **Text files**: no hard limit (subject to context window)
+
+### Rate Limits
+
+- Subject to Gemini API free tier limits
+- Daily usage quotas apply
+- Automatic retry on temporary failures
+
+### Context Window
+
+- Maximum 1M tokens
+- Approximately 750k words
+- Or ~3000 pages of text
+
+## Troubleshooting
+
+### Gemini CLI Not Found
+
+```bash
+Error: Gemini CLI not found at /opt/homebrew/bin/gemini
+```
+
+**Solution:**
+```bash
+# Install via Homebrew
+brew install gemini-cli
+
+# Or verify installation path
+which gemini
+```
+
+### Timeout Errors
+
+```bash
+Error: Command timeout after 120000ms
+```
+
+**Solution:**
+```bash
+# Use thinking model for complex queries
+/gemini -m gemini-2.0-flash-thinking-exp <your query>
+
+# Or increase timeout (requires config change)
+```
+
+### File Not Found
+
+```bash
+Error: File not found: ./nonexistent.txt
+```
+
+**Solution:**
+- Verify file path is correct
+- Use absolute paths for clarity
+- Check file permissions
+
+### JSON Parsing Errors
+
+```bash
+Error: Failed to parse JSON output
+```
+
+**Solution:**
+```bash
+# Request explicit JSON format
+/gemini -o json <your query>
+
+# Or use text format
+/gemini -o text <your query>
+```
+
+## Best Practices
+
+### DO ✅
+
+- Use specific, clear queries
+- Specify model for complex tasks
+- Include relevant file references
+- Use JSON output for structured data
+- Break large tasks into smaller queries
+
+### DON'T ❌
+
+- Include sensitive data in queries
+- Process untrusted files without review
+- Exceed rate limits with rapid requests
+- Rely solely on Gemini for code implementation
+- Ignore security warnings
+
+## Advanced Usage
+
+### Chaining Commands
+
+```bash
+# Step 1: Analyze
+/gemini -o json Analyze this codebase architecture ./src
+
+# Step 2: Use results
+Based on the analysis, implement the suggested improvements
+
+# Step 3: Verify
+/gemini Review the implemented changes
+```
+
+### Custom Models
+
+```bash
+# Use experimental thinking model
+/gemini -m gemini-2.0-flash-thinking-exp Solve this complex algorithm problem
+
+# Use standard model for simple tasks
+/gemini -m gemini-2.0-flash Quick question about syntax
+```
+
+### Batch Processing
+
+```bash
+# Process multiple files
+/gemini -f ./docs/spec.md,./src/index.ts,./tests/unit.test.ts Analyze consistency across these files
+```
+
+## Related Documentation
+
+- [SubAgent Documentation](../../agents/gemini-executor/README.md) - Technical implementation details
+- [Architecture Guide](../../docs/architecture.md) - System design and patterns
+- [Contributing Guide](../../CONTRIBUTING.md) - How to contribute
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/mokasz/gemini-executor/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/mokasz/gemini-executor/discussions)
+- **Documentation**: [Full Documentation](../../README.md)
+
+---
+
+**Tip**: Start with simple queries to get familiar with the skill, then explore advanced features like interactive mode and custom models.