gemini-executor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mokasz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# Gemini Executor
+
+> **Seamlessly integrate Google's Gemini CLI with Claude Code for powerful AI collaboration**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
+
+Gemini Executor is an integration layer that combines the strengths of **Claude Code** and **Google's Gemini CLI**, enabling them to work together as complementary AI assistants. Claude handles precise code editing and project operations, while Gemini provides creative reasoning, data analysis, and multimodal processing with its 1M token context window.
+
+## ✨ Key Features
+
+- **🎯 Complementary AI Strengths** - Claude for code precision, Gemini for creative reasoning
+- **📦 Context Isolation** - Gemini's large outputs don't pollute your main conversation
+- **🔒 Security First** - Built-in sanitization, validation, and sensitive file detection
+- **🚀 Zero Config** - Works with existing Gemini CLI installation
+- **🎨 Multimodal Ready** - Process images, PDFs, audio, and video files
+- **💰 Cost Effective** - Leverages Gemini's generous free tier
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Claude Code                        │
+│                                                      │
+│  ┌────────────────┐         ┌──────────────────┐  │
+│  │  User Request  │────────▶│   Task Router    │  │
+│  └────────────────┘         └──────────────────┘  │
+│                                     │               │
+│                    ┌────────────────┴───────────┐  │
+│                    │                            │  │
+│            ┌───────▼────────┐         ┌────────▼──────────┐
+│            │  Claude Agent  │         │  Gemini SubAgent  │
+│            │                │         │                   │
+│            │ • Code Editing │         │ • Complex Logic   │
+│            │ • File Ops     │         │ • Data Analysis   │
+│            │ • Git Ops      │         │ • Creative Tasks  │
+│            └────────────────┘         └─────────┬─────────┘
+│                                                  │
+│                                       ┌──────────▼─────────┐
+│                                       │   Gemini CLI       │
+│                                       └────────────────────┘
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Design Pattern: "Thin Skill + Universal SubAgent"
+
+- **Thin Skill**: Lightweight `/gemini` command for user interaction
+- **Universal SubAgent**: Reusable `gemini-executor` agent for programmatic delegation
+- **Context Isolation**: Long outputs processed separately from main conversation
+
+## 📋 Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Claude Code** (CLI tool)
+- **Gemini CLI** >= 1.0.0
+
+Install Gemini CLI:
+```bash
+# macOS
+brew install gemini-cli
+
+# Or via pip
+pip install gemini-cli
+```
+
+## 🚀 Installation
+
+### Option 1: Clone and Install
+
+```bash
+git clone https://github.com/mokasz/gemini-executor.git
+cd gemini-executor
+npm install
+npm run build
+```
+
+### Option 2: npm (coming soon)
+
+```bash
+npm install -g gemini-executor
+```
+
+## 📖 Usage
+
+### As a SubAgent (Programmatic)
+
+Claude can automatically delegate tasks to Gemini:
+
+```typescript
+// Claude internally uses:
+Task({
+  subagent_type: 'gemini-executor',
+  prompt: 'Analyze this large codebase and identify architectural patterns',
+  description: 'Analyze codebase architecture'
+})
+```
+
+**Use Cases:**
+- Large project analysis (leveraging 1M token context)
+- Complex algorithm design
+- Data analysis and interpretation
+- Creative problem-solving
+
+### As a Skill (Command Line)
+
+Users can directly invoke Gemini:
+
+```bash
+# Simple query
+/gemini Explain how dependency injection works
+
+# With specific model
+/gemini -m gemini-2.0-flash-thinking-exp Design a caching strategy
+
+# JSON output
+/gemini -o json Extract UI components from this image
+
+# Interactive mode
+/gemini -i Let's brainstorm ideas for...
+```
+
+**Use Cases:**
+- Quick questions and clarifications
+- Multimodal file processing (images, PDFs, audio, video)
+- Alternative perspectives on problems
+- Iterative problem-solving
+
+## 🎨 Real-World Examples
+
+### Example 1: Analyze Large Codebase
+
+```bash
+# Claude delegates to Gemini for full project analysis
+User: "Analyze the entire project structure and suggest improvements"
+Claude: [Uses gemini-executor agent]
+Gemini: [Reads all files with 1M context, provides comprehensive analysis]
+Claude: [Implements suggested improvements]
+```
+
+### Example 2: Process UI Design Image
+
+```bash
+# Direct skill invocation for multimodal task
+/gemini Analyze this UI design and extract component specs design.png
+```
+
+### Example 3: Complex Algorithm Design
+
+```bash
+User: "Design an efficient LRU cache with O(1) operations"
+Claude: "Let me consult Gemini for algorithm design"
+Claude: [Delegates to gemini-executor]
+Gemini: [Provides algorithm design with trade-offs]
+Claude: [Implements the algorithm in code]
+```
+
+## 🔒 Security Features
+
+- **Path Validation**: Prevents directory traversal attacks
+- **Command Injection Prevention**: Sanitizes all shell inputs
+- **Sensitive File Detection**: Warns before processing `.env`, credentials, etc.
+- **API Key Protection**: Never logs or exposes API keys
+- **Input Sanitization**: Escapes special characters in user input
+
+## 🎯 Complementary Strengths
+
+| Capability | Claude | Gemini |
+|------------|--------|--------|
+| Code Editing | ⭐⭐⭐⭐⭐ | ⭐⭐ |
+| File Operations | ⭐⭐⭐⭐⭐ | - |
+| Git Operations | ⭐⭐⭐⭐⭐ | - |
+| Multimodal Processing | ⭐ | ⭐⭐⭐⭐⭐ |
+| Super-long Context (1M tokens) | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| Free Tier | - | ⭐⭐⭐⭐⭐ |
+
+## 📂 Project Structure
+
+```
+gemini-executor/
+├── agents/               # SubAgent implementations
+│   └── gemini-executor/  # Main Gemini executor agent
+├── skills/               # Skill implementations
+│   └── gemini/          # User-facing /gemini command
+├── docs/                # Documentation
+│   └── architecture.md  # Detailed architecture guide
+├── LICENSE              # MIT License
+├── package.json         # Project metadata
+└── README.md           # This file
+```
+
+## 🛠️ Development
+
+### Setup Development Environment
+
+```bash
+# Install dependencies
+npm install
+
+# Run in watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+Output will be in `dist/` directory.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development Roadmap
+
+- [x] Architecture design
+- [x] Documentation
+- [ ] SubAgent implementation (`agents/gemini-executor/`)
+- [ ] Skill implementation (`skills/gemini/`)
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] CI/CD pipeline
+- [ ] npm package publication
+
+## 📊 Status
+
+| Component | Status | Progress |
+|-----------|--------|----------|
+| Architecture | ✅ Complete | 100% |
+| Documentation | ✅ Complete | 100% |
+| SubAgent Implementation | ⏳ Planned | 0% |
+| Skill Implementation | ⏳ Planned | 0% |
+| Tests | ⏳ Planned | 0% |
+
+**Overall Progress**: 35% (Design phase complete, implementation pending)
+
+## 📚 Documentation
+
+- [Architecture Overview](docs/architecture.md) - Detailed system design
+- [Analysis Report](ANALYSIS_REPORT.md) - Comprehensive analysis from Gemini
+- [Strategic Summary](STRATEGIC_SUMMARY.md) - Executive overview
+- [Quick Reference](QUICK_REFERENCE.md) - Developer handbook
+- [Analysis Index](ANALYSIS_INDEX.md) - Documentation navigation
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Claude Code** by Anthropic - For providing the foundation and integration capabilities
+- **Google Gemini** - For the powerful AI capabilities and CLI tool
+- The open-source community for inspiration and best practices
+
+## 📮 Contact
+
+- **Author**: mokasz
+- **Issues**: [GitHub Issues](https://github.com/mokasz/gemini-executor/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/mokasz/gemini-executor/discussions)
+
+---
+
+**Made with ❤️ by the AI community**

package/agents/gemini-executor/README.md

@@ -0,0 +1,315 @@
+# Gemini Executor SubAgent
+
+A specialized agent for executing Google's Gemini CLI commands from within Claude Code.
+
+## Overview
+
+This SubAgent provides a programmatic interface to Gemini CLI, allowing Claude to delegate tasks that benefit from Gemini's capabilities such as:
+
+- Complex reasoning and creative problem-solving
+- Large context analysis (1M tokens)
+- Multimodal processing (images, PDFs, audio, video)
+- Data analysis and interpretation
+
+## Architecture
+
+```
+Claude Code
+    │
+    ├─ Task Tool
+    │     │
+    │     └─ subagent_type: 'gemini-executor'
+    │            │
+    │            └─ Gemini Executor SubAgent
+    │                   │
+    │                   └─ Gemini CLI
+    │                          │
+    │                          └─ Google Gemini API
+```
+
+## Usage
+
+### From Claude Code (Internal)
+
+Claude can invoke this SubAgent via the Task tool:
+
+```typescript
+Task({
+  subagent_type: 'gemini-executor',
+  prompt: JSON.stringify({
+    query: 'Analyze this codebase architecture',
+    files: ['/path/to/project'],
+    outputFormat: 'text'
+  }),
+  description: 'Analyze codebase architecture'
+})
+```
+
+### Programmatic Usage
+
+```typescript
+import { execute, checkGeminiCLI } from './agents/gemini-executor';
+
+// Check if Gemini CLI is available
+const isAvailable = await checkGeminiCLI();
+if (!isAvailable) {
+  console.error('Gemini CLI is not installed');
+  process.exit(1);
+}
+
+// Execute a query
+const result = await execute({
+  query: 'Explain how dependency injection works',
+  model: 'gemini-2.0-flash',
+  outputFormat: 'text'
+});
+
+if (result.success) {
+  console.log('Output:', result.output);
+  console.log('Metadata:', result.metadata);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+## API Reference
+
+### `execute(options, config?)`
+
+Main execution function for Gemini CLI.
+
+**Parameters:**
+- `options: ExecutionOptions` - Execution options
+  - `query: string` - Query or prompt to send to Gemini (required)
+  - `model?: string` - Specific model to use
+  - `outputFormat?: 'text' | 'json' | 'stream-json'` - Output format
+  - `files?: string[]` - File paths to include in the prompt
+  - `workingDir?: string` - Working directory for file references
+  - `interactive?: boolean` - Enable interactive mode
+- `config?: Partial<GeminiConfig>` - Configuration overrides
+
+**Returns:** `Promise<ExecutionResult>`
+- `success: boolean` - Success status
+- `output?: string` - Output from Gemini
+- `error?: string` - Error message if failed
+- `metadata: object` - Execution metadata
+  - `model: string` - Model used
+  - `retries: number` - Number of retries
+  - `duration: number` - Execution duration in ms
+
+### `checkGeminiCLI(config?)`
+
+Check if Gemini CLI is installed and accessible.
+
+**Parameters:**
+- `config?: Partial<GeminiConfig>` - Configuration overrides
+
+**Returns:** `Promise<boolean>` - True if Gemini CLI is available
+
+## Configuration
+
+Default configuration:
+
+```typescript
+{
+  cliPath: '/opt/homebrew/bin/gemini',
+  defaultModel: 'gemini-2.0-flash',
+  maxRetries: 3,
+  timeout: 120000, // 2 minutes
+  yolo: true // Auto-confirm prompts
+}
+```
+
+Override configuration when calling `execute()`:
+
+```typescript
+const result = await execute(
+  { query: 'Your query' },
+  {
+    cliPath: '/custom/path/to/gemini',
+    defaultModel: 'gemini-2.0-flash-thinking-exp',
+    maxRetries: 5,
+    timeout: 300000 // 5 minutes
+  }
+);
+```
+
+## Security Features
+
+### Input Sanitization
+
+All user inputs are sanitized to prevent command injection:
+
+```typescript
+// Dangerous characters are removed or escaped
+sanitizeInput('hello; rm -rf /') // → 'hello rm -rf /'
+```
+
+### Path Validation
+
+File paths are validated to prevent directory traversal attacks:
+
+```typescript
+validateFilePath('../../../etc/passwd') // → Throws error
+validateFilePath('/legitimate/path') // → '/legitimate/path'
+```
+
+### Sensitive File Detection
+
+The SubAgent warns when processing potentially sensitive files:
+
+```typescript
+// Detects patterns like:
+// .env, credentials.json, *.key, *.pem, id_rsa, etc.
+```
+
+## Error Handling
+
+The SubAgent includes robust error handling:
+
+### Retry Logic
+
+Automatically retries failed requests with exponential backoff:
+
+```typescript
+// Attempt 1: immediate
+// Attempt 2: 1 second delay
+// Attempt 3: 2 second delay
+// etc.
+```
+
+### Timeout Protection
+
+Commands that exceed the timeout are automatically terminated:
+
+```typescript
+{
+  timeout: 120000 // 2 minutes default
+}
+```
+
+### Detailed Error Messages
+
+Errors include context for debugging:
+
+```typescript
+{
+  success: false,
+  error: 'Gemini CLI execution failed: timeout exceeded',
+  metadata: {
+    model: 'gemini-2.0-flash',
+    retries: 3,
+    duration: 120045
+  }
+}
+```
+
+## Output Formats
+
+### Text (Default)
+
+Plain text response from Gemini:
+
+```typescript
+await execute({
+  query: 'Explain async/await',
+  outputFormat: 'text'
+});
+// Returns plain text explanation
+```
+
+### JSON
+
+Structured JSON response:
+
+```typescript
+await execute({
+  query: 'Extract UI components from this design',
+  outputFormat: 'json'
+});
+// Returns parsed JSON object
+```
+
+### Stream JSON
+
+Real-time JSON updates:
+
+```typescript
+await execute({
+  query: 'Analyze large codebase',
+  outputFormat: 'stream-json'
+});
+// Returns streaming JSON for progress updates
+```
+
+## Examples
+
+### Example 1: Simple Query
+
+```typescript
+const result = await execute({
+  query: 'What are the benefits of TypeScript?'
+});
+```
+
+### Example 2: Code Analysis
+
+```typescript
+const result = await execute({
+  query: 'Analyze this code for potential issues',
+  files: ['./src/index.ts'],
+  workingDir: '/path/to/project'
+});
+```
+
+### Example 3: With Specific Model
+
+```typescript
+const result = await execute({
+  query: 'Design an optimal caching strategy',
+  model: 'gemini-2.0-flash-thinking-exp',
+  outputFormat: 'json'
+});
+```
+
+### Example 4: Large Context Analysis
+
+```typescript
+const result = await execute({
+  query: 'Analyze the entire project structure and identify architectural patterns',
+  files: ['./src', './docs', './tests'],
+  workingDir: '/path/to/large/project',
+  model: 'gemini-2.0-flash'
+});
+```
+
+## Debugging
+
+Enable verbose logging:
+
+```typescript
+// Set environment variable
+process.env.DEBUG = 'gemini-executor';
+
+// Or add console.log statements
+console.log('Command:', command);
+console.log('Result:', result);
+```
+
+## Limitations
+
+- **Gemini CLI Required**: Must have Gemini CLI installed
+- **File Size Limits**:
+  - Images: max 20MB
+  - PDFs/Audio/Video: max 100MB
+- **Context Window**: max 1M tokens
+- **Rate Limits**: Subject to Gemini API rate limits
+- **Free Tier**: Daily usage limits apply
+
+## Contributing
+
+See the main [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE)