claudegem/README.md

Seamless integration of Claude Code CLI + Gemini CLI for context-aware code reasoning

# claudegem

**Seamless integration of Claude Code CLI + Gemini CLI for context-aware code reasoning with MCP (Model Context Protocol) support.**

🚀 **Enhanced with MCP Server** - Now includes a powerful MCP server that provides Claude Code with internet search, AI fallbacks, and enhanced command execution capabilities from any directory!

## Features

### 🔥 **Core Features**
- **Dual AI Integration**: Combines Gemini's codebase analysis with Claude's code reasoning
- **Context-Aware Processing**: Gemini first analyzes your codebase, then provides context to Claude
- **Secure Command Execution**: Protected against command injection vulnerabilities
- **Global CLI Tool**: Use from any directory once installed

### 🚀 **MCP Server Features (NEW)**
- **🌐 Internet Search**: Search the web for current information, documentation, and tutorials
- **🤖 AI Fallback System**: Automatic fallback to Llama 3.2 → Mistral when Gemini quota exhausted
- **⚡ Enhanced Commands**: Execute bash commands through AI with intelligent processing
- **📁 Cross-Directory**: Works from any folder on your system
- **🔒 Privacy-Focused**: Uses DuckDuckGo for web search (no tracking)
- **🎯 Real-time Info**: Access current news, trends, and documentation beyond training data

## Prerequisites

### Required CLI Tools
- **Claude CLI**: [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- **Gemini CLI**: [Install Gemini CLI](https://github.com/Vimplify/gemini-cli)

### Optional (for MCP Fallbacks)
- **Ollama**: [Install Ollama](https://ollama.ai) for local AI model fallbacks
- **Models**: `ollama pull llama3.2` and `ollama pull mistral` (for fallback support)

## Installation

### Global Installation (Recommended)

```bash
npm install -g claudegem
```

### Local Installation

```bash
npm install claudegem
```

## Usage

### 🎯 **MCP Mode (Recommended for Enhanced Features)**

Start Claude Code with the ClaudeGem MCP server for enhanced capabilities:

```bash
# Start from ANY directory - works globally!
claudegem --mcp

# Works from your home directory
cd ~
claudegem --mcp

# Works from any project folder
cd /path/to/your/project
claudegem --mcp

# Works from system directories
cd /usr/local
claudegem --mcp
```

**In the Claude Code session, you'll have access to:**

#### 🌐 **Internet Search**
```
Search the internet for "latest React 18 features"
Find current Node.js security best practices
Look up recent AI developments 2024
```

#### ⚡ **AI-Enhanced Commands**
```
Use bash_with_gemini to run: ls -la && git status
Execute this command with AI assistance: npm install --save react
```

#### 🔍 **Code Analysis with Fallbacks**
```
Analyze this React component with AI assistance
Review this Python function for potential issues
```

### 📁 **Using MCP Across Different Directories**

The MCP server works seamlessly across different folders:

```bash
# Web Development Project
cd ~/projects/my-react-app
claudegem --mcp
# Now Claude Code has context of your React project + internet search

# Python Data Science Project  
cd ~/data-science/ml-project
claudegem --mcp
# Now Claude Code understands your Python environment + can search for ML docs

# DevOps/Infrastructure
cd ~/infrastructure/kubernetes
claudegem --mcp
# Claude Code can help with K8s configs + search for latest practices

# Documentation Writing
cd ~/documentation/api-docs
claudegem --mcp
# Get writing help + search for current API documentation standards
```

### 🔥 **Basic Usage (Single Queries)**

```bash
claudegem "your query here"
```

### 🛠️ **Advanced Usage with Claude CLI Flags**

```bash
# Use Claude with specific flags
claudegem "analyze this code" --claude-flags="--debug"

# Skip Gemini context gathering
claudegem "simple query" --skip-gemini

# Use different Gemini model
claudegem "complex analysis" --gemini-model="gemini-2.5-flash"
```

### 🔄 **Automatic Fallback System**

When **Gemini API quota is exhausted**, claudegem automatically switches to **free local alternatives**:

1. **Llama 3.2** (via Ollama) - Fast fallback (~3-7 seconds)
2. **Mistral Devstral Medium** (via Ollama) - Specialized coding fallback

```bash
# Fallbacks work automatically in both modes:
claudegem "query" --fallback="llama,mistral"
claudegem --mcp  # Fallbacks also work in MCP mode

# Clear terminal messaging when switching:
# 🚨 GEMINI API QUOTA EXHAUSTED - Switching to free alternatives...
# 🦙 Using Llama as fallback due to Gemini quota exhaustion
# 🔮 Using Mistral as fallback due to Gemini quota exhaustion
```

## 🎯 **Benefits of ClaudeGem MCP**

### 🚀 **Enhanced Capabilities**
- **Current Information**: Access real-time web data beyond AI training cutoffs
- **Cross-Directory Support**: Use from any folder without setup
- **Multiple AI Models**: Automatic fallback ensures continuous availability
- **Privacy-Focused**: DuckDuckGo search with no tracking
- **Fast Responses**: 3-5 seconds for web search, 3-7 seconds for local AI fallbacks

### 💼 **Professional Benefits**
- **Stay Current**: Get latest documentation, frameworks, and best practices
- **Cost Effective**: Free local fallbacks when API quotas exhausted
- **No Vendor Lock-in**: Works with multiple AI providers
- **Enhanced Productivity**: AI-assisted command execution and analysis
- **Global Access**: Works from any directory or project

### 🛠️ **Developer Benefits**
- **Latest Tech Info**: "What's new in React 19?", "Latest Node.js security patches"
- **Documentation Search**: Find current API docs, tutorials, examples
- **Troubleshooting**: Search for recent solutions to specific errors
- **Trend Analysis**: Discover emerging tools and frameworks
- **Code Context**: AI understands your project + can search for related info

### 🔐 **Security & Privacy**
- **No API Keys for Search**: Uses DuckDuckGo without requiring accounts
- **Local AI Fallbacks**: Llama/Mistral run locally (no data sent to external APIs)
- **Secure Command Execution**: Protected against injection vulnerabilities
- **Privacy-First**: DuckDuckGo doesn't track or store search history

## 🌟 **Real-World Use Cases**

### 🌐 **Web Development**
```bash
cd ~/my-react-app
claudegem --mcp

# In Claude Code session:
"Search for latest React 18 performance best practices"
"What are the new features in Next.js 14?"
"Find current CSS-in-JS library recommendations"
"Look up recent TypeScript 5.0 changes"
```

### 🐍 **Python Development**
```bash
cd ~/ml-project
claudegem --mcp

# In Claude Code session:
"Search for latest scikit-learn 2024 updates"
"Find current PyTorch best practices for transformers"
"Look up recent pandas performance improvements"
"What are the latest Python security vulnerabilities?"
```

### ⚙️ **DevOps & Infrastructure**
```bash
cd ~/infrastructure
claudegem --mcp

# In Claude Code session:
"Search for Kubernetes 1.28 new features"
"Find current Docker security best practices 2024"
"Look up latest Terraform provider updates"
"What are recent AWS service announcements?"
```

### 📱 **Mobile Development**
```bash
cd ~/mobile-app
claudegem --mcp

# In Claude Code session:
"Search for React Native 0.73 breaking changes"
"Find current iOS 17 development guidelines"
"Look up latest Flutter 3.16 features"
"What are recent Android development best practices?"
```

## 📋 **MCP Tools Available**

When using `claudegem --mcp`, Claude Code gets access to these enhanced tools:

### 🌐 **search_internet**
```
Search the internet for "latest JavaScript frameworks 2024"
Find documentation for "Supabase real-time subscriptions"
Look up "Node.js 20 breaking changes"
```

### ⚡ **bash_with_gemini** 
```
Use bash_with_gemini to run: git log --oneline -10
Execute with AI help: npm audit fix
Run system check: df -h && free -m
```

### 🔍 **analyze_with_gemini**
```
Analyze this React component for performance issues
Review this SQL query for optimization opportunities
Check this Python function for potential bugs
```

## 💡 **Quick Examples**

### 🔥 **MCP Mode (Recommended)**
```bash
# Enhanced mode with internet search + AI fallbacks
claudegem --mcp
```

### ⚡ **Basic Mode**
```bash
# Basic analysis with context
claudegem "What files are in this project?"

# Code explanation with tools
claudegem "Explain how authentication works" --claude-flags="--tools"

# Direct Claude usage (no Gemini context)
claudegem "Simple question" --skip-gemini

# Fast processing with Gemini Flash
claudegem "Quick code review" --gemini-model="gemini-2.5-flash"
```

## How It Works

1. **Dependency Check**: Verifies both Claude and Gemini CLIs are available
2. **Context Gathering**: Gemini analyzes your codebase and identifies relevant files
3. **Context Enhancement**: Filters and cleans Gemini's output
4. **Query Processing**: Sends enhanced query with context to Claude
5. **Result Delivery**: Returns Claude's context-aware response

## Configuration

### Default Settings
- **Gemini**: `gemini-2.5-pro` model with debug output
- **Claude**: `--print` flag for text output

### Available Options
- `--claude-flags`: Pass any Claude CLI flags (e.g., `--tools`, `--memory`, `--interactive`)
- `--skip-gemini`: Skip Gemini context gathering for faster processing
- `--gemini-model`: Choose Gemini model (`gemini-2.5-pro`, `gemini-2.5-flash`, etc.)

### Supported Claude CLI Modes
- **Text output**: `--print` (default and recommended)
- **Debug mode**: `--debug`
- **JSON output**: `--output-format json`
- **Continue session**: `--continue`
- **Resume session**: `--resume`
- **Model selection**: `--model`
- **Tool restrictions**: `--allowedTools`, `--disallowedTools`

### Interactive Session Support (Experimental)
- Basic interactive session support with command delegation to Gemini
- **Note**: Full interactive session with tool interception is experimental and may not work perfectly with all Claude Code features

## Troubleshooting

### Common Issues

1. **CLI Not Found**: Ensure both Claude and Gemini CLIs are installed and in your PATH
2. **Permission Errors**: Make sure the CLI tools have proper permissions
3. **Timeout Issues**: Complex queries may take up to 30 seconds

### Debug Mode

Both CLIs run with verbose output for debugging. Check the terminal output for detailed execution steps.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Repository

[GitHub Repository](https://github.com/frankingstyl/claudegem)