strangekid7822/gemini-supervisor

Gemini Supervisor 🤖

An MCP (Model Context Protocol) server that allows Claude to autonomously supervise and control Google's Gemini CLI. Perfect for leveraging Gemini's free tier while having Claude orchestrate complex, multi-step tasks.

🎯 What This Does

• Autonomous Operation: Give Claude a mission, let it supervise Gemini CLI to complete the work
• Free Labor: Uses Gemini 2.5 Flash's generous free tier (60 requests/min, 1000/day)
• Smart Supervision: Claude breaks down tasks, analyzes results, and decides next steps
• Portable: Works on any macOS with Node.js and Python

🚀 Quick Start

⚡ One-Command Installation (Easiest)

curl -fsSL https://raw.githubusercontent.com/strangekid7822/gemini-supervisor/main/install-easy.sh | bash

This automatically installs:

• Node.js (if needed)
• Gemini CLI
• Python dependencies
• Configures Claude Code
• Sets up authentication

🔧 Manual Installation

Prerequisites: Python 3.8+, Node.js 18+

# 1. Install Gemini CLI
npm install -g @google/gemini-cli

# 2. Authenticate Gemini (choose Google login)
gemini

# 3. Install Gemini Supervisor
git clone https://github.com/strangekid7822/gemini-supervisor.git
cd gemini-supervisor
pip3 install -e . --break-system-packages

# 4. Add to Claude Code
claude mcp add gemini-supervisor "python3" -m gemini_supervisor.server -s user

Manual MCP Configuration:

{
  "gemini-supervisor": {
    "command": "python3",
    "args": ["-m", "gemini_supervisor.server"]
  }
}

🛠️ Usage

Basic Gemini Control

# Simple questions to Gemini
> ask_gemini "What is the capital of France?"

# Include file context
> ask_gemini_with_files "Explain this code" files=["main.py"]

# Include all files in directory
> ask_gemini_with_files "Review this codebase" all_files=true

Autonomous Missions

# Start a mission - Claude will supervise Gemini to complete it
> start_mission "Analyze this Python project and create comprehensive documentation"

# Check progress
> get_mission_status

# Continue with modifications
> continue_mission "Also add code examples to the documentation"

🏗️ How It Works

You → Claude → Gemini Supervisor → Gemini CLI → Gemini API
     ↑                           ↑
     ├── Orchestrates mission    └── Does the heavy lifting
     ├── Analyzes results              (uses free quota)
     └── Decides next steps

Mission Flow

1. You: Give Claude a mission and leave
2. Claude: Breaks mission into steps using TodoWrite
3. Gemini CLI: Executes each step using free Gemini 2.5 Flash
4. Claude: Reviews results, decides if step succeeded
5. Repeat: Until mission complete or intervention needed

📋 Available Tools

🎯 Example Missions

Code Documentation

start_mission "Create comprehensive documentation for this Python project including API docs, usage examples, and setup instructions"

Code Review & Refactoring

start_mission "Review this codebase for bugs, performance issues, and suggest improvements with specific code changes"

Test Suite Creation

start_mission "Analyze this code and create a complete test suite with unit tests, integration tests, and test data"

Project Analysis

start_mission "Analyze this repository structure, dependencies, and create a technical overview with architecture diagrams"

📁 Project Structure

gemini-supervisor/
├── README.md                    # This file
├── setup.py                     # Package configuration
├── requirements.txt             # Python dependencies
├── install.sh                   # One-click installer
└── gemini_supervisor/
    ├── __init__.py             # Package info
    ├── server.py               # Main MCP server
    ├── gemini_controller.py    # Gemini CLI interface
    └── mission_manager.py      # Mission planning & tracking

🔧 Configuration

Working Directory

The supervisor works in your current directory by default. Specify a different directory when starting missions:

start_mission "Analyze this project" working_directory="/path/to/project"

Mission Persistence

Missions are saved as JSON files in the working directory:

• mission_1692123456.json - Contains mission state, steps, results

🚨 Troubleshooting

Gemini CLI Not Found

# Install Gemini CLI
npm install -g @google/gemini-cli

# Verify installation
which gemini
gemini --version

Authentication Issues

# Re-authenticate Gemini CLI
gemini
# Choose "Login with Google" for free tier

MCP Server Not Starting

# Test the server directly
python3 -m gemini_supervisor.server

# Check Python imports
python3 -c "import gemini_supervisor"

# If installation fails due to externally managed environment
pip3 install -e . --break-system-packages

Mission Planning Fails

• Ensure Gemini CLI is authenticated
• Check that mission description is clear and specific
• Verify working directory has proper permissions

🎉 Success Tips

1. Clear Missions: Be specific about what you want accomplished
2. Proper Setup: Ensure Gemini CLI works standalone first
3. Free Tier: Uses Gemini's generous free limits (60/min, 1000/day)
4. Patience: Let Claude supervise - it will break down complex tasks
5. Monitor: Check get_mission_status to see progress

🔄 Sharing & Portability

To use on any Mac globally:

1. Copy this directory to the new Mac
2. Install globally: pip3 install .
3. Add to Claude Code: claude mcp add gemini-supervisor gemini-supervisor -s user
4. Restart Claude Code and it works from any directory!

For teams: Share the repository, everyone installs globally, and it works consistently across all machines.

Built with ❤️ for autonomous AI collaboration

Let Claude supervise, let Gemini work, let you focus on what matters.