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
• Gemini CLI: Install Gemini CLI

Optional (for MCP Fallbacks)

• Ollama: Install Ollama for local AI model fallbacks
• Models: ollama pull llama3.2 and ollama pull mistral (for fallback support)

Installation

Global Installation (Recommended)

npm install -g claudegem

Local Installation

npm install claudegem

Usage

🎯 MCP Mode (Recommended for Enhanced Features)

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

# 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:

# 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)

claudegem "your query here"

🛠️ Advanced Usage with Claude CLI Flags

# 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

# 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

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

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

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

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)

# Enhanced mode with internet search + AI fallbacks
claudegem --mcp

⚡ Basic Mode

# 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