Recent Improvements (v2.5.0)

🛡️ Enhanced Error Resilience

• Malformed Chunk Recovery: Automatically detects and handles malformed JSON chunks from Gemini streaming
• Smart Retry Logic: Exponential backoff with configurable retry limits for streaming errors
• Graceful Fallback: Seamlessly switches to non-streaming mode when streaming fails
• Buffer Management: Intelligent chunk buffering and reconstruction for incomplete JSON
• Connection Stability: Handles Gemini 500 Internal Server Errors with automatic retry

📊 Improved Monitoring

• Detailed Error Classification: Specific guidance for different types of Gemini API errors
• Enhanced Logging: Comprehensive error tracking with malformed chunk statistics
• Real-time Status: Better health checks and connection testing

Prerequisites

• A Google Gemini API key.
• Python 3.8+.
• Claude Code CLI installed (e.g., npm install -g @anthropic-ai/claude-code).

Setup

1. Clone the repository:

   git clone https://github.com/coffeegrind123/gemini-code.git # Or your fork
   cd gemini-code
   

2. Create and activate a virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure Environment Variables: Copy the example environment file:

   cp .env.example .env
   

   Edit .env and add your Gemini API key. You can also customize model mappings and server settings:

   # Required: Your Google AI Studio API key
   GEMINI_API_KEY="your-google-ai-studio-key"
   
   # Optional: Model mappings for Claude Code aliases
   BIG_MODEL="gemini-1.5-pro-latest"    # For 'sonnet' or 'opus' requests
   SMALL_MODEL="gemini-1.5-flash-latest" # For 'haiku' requests
   
   # Optional: Server settings
   HOST="0.0.0.0"
   PORT="8082"
   LOG_LEVEL="WARNING"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
   
   # Optional: Performance and reliability settings
   MAX_TOKENS_LIMIT="8192"           # Max tokens for Gemini responses
   REQUEST_TIMEOUT="90"              # Request timeout in seconds
   MAX_RETRIES="2"                   # LiteLLM retries to Gemini
   MAX_STREAMING_RETRIES="12"         # Streaming-specific retry attempts
   
   # Optional: Streaming control (use if experiencing issues)
   FORCE_DISABLE_STREAMING="false"     # Disable streaming globally
   EMERGENCY_DISABLE_STREAMING="false" # Emergency streaming disable
   

5. Run the server: The server.py script includes a main() function that starts the Uvicorn server:

   python server.py
   

   For development with auto-reload (restarts when you save changes to server.py):

   uvicorn server:app --host 0.0.0.0 --port 8082 --reload
   

   You can view all startup options, including configurable environment variables, by running:

   python server.py --help
   

Usage with Claude Code

1. Start the Proxy Server: Ensure the Gemini proxy server (this application) is running (see step 5 above).

2. Configure Claude Code to Use the Proxy: Set the ANTHROPIC_BASE_URL environment variable when running Claude Code:

   ANTHROPIC_BASE_URL=http://localhost:8082 claude
   

   Replace localhost:8082 if your proxy is running on a different host or port.

3. Utilize CLAUDE.md for Optimal Gemini Performance (Crucial):

   • This repository includes a CLAUDE.md file. This file contains specific instructions and best practices tailored to help Gemini effectively understand and respond to Claude Code's unique command structure, tool usage patterns, and desired output formats.

   • Copy CLAUDE.md into your project directory:

     cp /path/to/gemini-code/CLAUDE.md /your/project/directory/
     

   • When starting a new conversation with Claude Code in that directory, begin with:

     First read and process CLAUDE.md with intent. After understanding and agreeing to use the policies and practices outlined in the document, respond with YES
     

   • This ensures Gemini receives important context and instructions for better assistance.

   • If Gemini still fucks up, ask it to read CLAUDE.md again. This might or might not help!

How It Works: Powering Claude Code with Gemini

1. Claude Code Request: You issue a command or prompt in the Claude Code CLI.
2. Anthropic Format: Claude Code sends an API request (in Anthropic's Messages API format) to the proxy server's address (http://localhost:8082).
3. Proxy Translation (Anthropic to Gemini): The proxy server:
   • Receives the Anthropic-formatted request.
   • Validates it and maps any Claude model aliases (like claude-3-sonnet...) to the corresponding Gemini model specified in your .env (e.g., gemini-1.5-pro-latest).
   • Translates the message structure, content blocks, and tool definitions into a format LiteLLM can use with the Gemini API.
4. LiteLLM to Gemini: LiteLLM sends the prepared request to the target Gemini model using your GEMINI_API_KEY.
5. Gemini Response: Gemini processes the request and sends its response back through LiteLLM.
6. Proxy Translation (Gemini to Anthropic): The proxy server:
   • Receives the Gemini response from LiteLLM (this can be a stream of events or a complete JSON object).
   • Handles streaming errors and malformed chunks with intelligent recovery.
   • Converts Gemini's output (text, tool calls, stop reasons) back into the Anthropic Messages API format that Claude Code expects.
7. Response to Claude Code: The proxy sends the Anthropic-formatted response back to your Claude Code client, which then displays the result or performs the requested action.

Model Mapping for Claude Code

To ensure Claude Code's model requests are handled correctly by Gemini:

• Requests from Claude Code for model names containing "haiku" (e.g., claude-3-haiku-20240307) are mapped to the Gemini model specified by your SMALL_MODEL environment variable (default: gemini-1.5-flash-latest).
• Requests from Claude Code for model names containing "sonnet" or "opus" (e.g., claude-3-sonnet-20240229, claude-3-opus-20240229) are mapped to the Gemini model specified by your BIG_MODEL environment variable (default: gemini-1.5-pro-latest).
• If Claude Code requests a full Gemini model name (e.g., gemini/gemini-1.5-pro-latest), the proxy will use that directly.

The server maintains a list of known Gemini models. If a recognized Gemini model is requested by the client without the gemini/ prefix, the proxy will add it.

Endpoints

• POST /v1/messages: The primary endpoint for Claude Code to send messages to Gemini. It's fully compatible with the Anthropic Messages API specification that Claude Code uses.
• POST /v1/messages/count_tokens: Allows Claude Code to estimate the token count for a set of messages, using Gemini's tokenization.
• GET /health: Returns the health status of the proxy, including API key configuration, streaming settings, and basic API key validation.
• GET /test-connection: Performs a quick API call to Gemini to verify connectivity and that your GEMINI_API_KEY is working.
• GET /: Root endpoint providing a welcome message, current configuration summary (models, limits), and available endpoints.

Error Handling & Troubleshooting

Common Issues and Solutions

Streaming Errors (malformed chunks):

• The proxy automatically handles malformed JSON chunks from Gemini
• If streaming becomes unstable, set FORCE_DISABLE_STREAMING=true as a temporary fix
• Increase MAX_STREAMING_RETRIES for more resilient streaming

Gemini 500 Internal Server Errors:

• The proxy automatically retries with exponential backoff
• These are temporary Gemini API issues that resolve automatically
• Check /health endpoint to monitor API status

Connection Timeouts:

• Increase REQUEST_TIMEOUT if experiencing frequent timeouts
• Check your internet connection and firewall settings
• Use /test-connection endpoint to verify API connectivity

Rate Limiting:

• Monitor your Google AI Studio quota in the Google Cloud Console
• The proxy will provide specific rate limi