Claude Code Proxy

English | 中文

A high-performance proxy that lets Claude Code use Google Gemini models.

---

Quick Start

1. Start the Proxy

# Build
cargo build --release

# Set API key and start
export GEMINI_API_KEY="your-gemini-api-key"
RUST_LOG=info cargo run --release

The proxy starts on http://127.0.0.1:8111 by default.

2. Configure Claude Code

# In a new terminal
export ANTHROPIC_BASE_URL=http://localhost:8111
export ANTHROPIC_AUTH_TOKEN="your-gemini-api-key"
export ANTHROPIC_MODEL=gemini-2.0-flash-exp

# Optional: Fine-tune model selection
export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.0-flash-exp
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.0-flash-exp
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.0-flash-exp
export CLAUDE_CODE_SUBAGENT_MODEL=gemini-2.0-flash-exp

# Use Claude Code normally!
claude-code

---

Why?

• 💰 Save Money: Gemini has a free tier, Claude doesn't
• 📚 Larger Context: Gemini supports 2M tokens vs Claude's 200K
• ⚡ Fast: Gemini 2.0 Flash is blazingly fast
• 🔧 Same Tools: Keep using Claude Code's excellent interface
• 🧠 Thinking Mode: Full support for Gemini 3 Pro Preview with thinking

---

Features

• ✅ Zero Config - Just set API key
• ✅ Transparent - Claude Code works normally
• ✅ Streaming - Real-time SSE responses
• ✅ Thinking Support - Handles Gemini 3 Pro Preview thinking mode
• ✅ Fast - Built with Axum and Reqwest
• ✅ Production Ready - 76 tests passing

---

Architecture

Built with modern Rust async stack:

• Axum - Web framework
• Reqwest - HTTP client
• Tokio - Async runtime
• Serde - Serialization

Key Components

• handler.rs - Request routing and SSE streaming
• client.rs - Gemini API client
• transform/ - Claude ↔ Gemini protocol translation
• streaming/ - SSE event generation and parsing
• models/ - Type-safe API models

---

Recent Improvements

v0.2.1 (2025-11-19) - CRITICAL FIX: Thought Signature Handling

• ✅ Fixed "Unknown name thoughtSignature" errors - Correctly identified that thoughtSignature is response-only
• ✅ Proper API compliance - thoughtSignature is never included in requests (only in responses)
• ✅ Simplified implementation - Removed complex fallback logic that was unnecessary
• ✅ Prevents 400 errors - No more "Invalid JSON payload received. Unknown name 'thoughtSignature'" errors
• ✅ Production tested - All 137 tests passing

v0.2.0 (2025-11-19) - MAJOR UPDATE: Full Tool Calling Support

• ✅ Complete tool calling implementation (Phases 1-7)
• ✅ All 11 Claude Code tools now work (TodoWrite, Task, Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, WebFetch, WebSearch)
• ✅ State management for multi-turn tool conversations
• ✅ Schema caching for 10x performance boost
• ✅ Performance metrics and monitoring
• ✅ Comprehensive schema validation
• ✅ Thought signature handling for Gemini 3 Pro
• ✅ 137 tests passing (was 76)
• ✅ Zero clippy warnings

---

Tool Calling

The proxy now fully supports Claude Code's tool calling system:

Supported Tools (11 total):

• ✅ TodoWrite - Task tracking
• ✅ Task - Subagent spawning
• ✅ Bash - Shell commands
• ✅ Read/Edit/Write - File operations
• ✅ Glob/Grep - Search operations
• ✅ AskUserQuestion - User interaction
• ✅ WebFetch/WebSearch - Web access

Features:

• Bidirectional transformation (Claude ↔ Gemini)
• Multi-turn conversations with state tracking
• Schema caching (<0.2ms overhead)
• Automatic validation
• Performance metrics
• Thought signature management (Gemini 3 Pro requirement)

Thought Signature Handling

For Gemini 3 Pro, the proxy correctly handles thought signatures at the Part level:

1. Response Processing: When Gemini returns function calls with thoughtSignature, it's cached in DashMap state
2. Request Processing: When resending conversation history, thoughtSignature is included at the Part level (not inside functionCall)
3. Correct Structure:

   {
     "functionCall": {"name": "tool", "args": {...}},
     "thoughtSignature": "<signature>"
   }

4. Smart Fallback: Uses cached signature when available, or "context_engineering_is_the_way_to_go" as fallback

Key Insight: thoughtSignature is a sibling field to functionCall at the Part level, NOT a field inside the functionCall object itself.

See TOOL_CALLING_GUIDE.md for testing guide.

---

Documentation

• README_EN.md - Complete English guide
• README_CN.md - 完整中文指南
• TOOL_CALLING_GUIDE.md - Tool calling testing guide
• specs/0005-tool-use.md - Technical specification
• DEPLOYMENT.md - Production deployment

---

Status

• Version: 0.2.1
• Tests: 137/137 Passing ✅ (+2 ignored for global state)
• Tool Calling: Full Support ✅
• Gemini 3 Pro: Full Compatibility ✅
• Quality: Production Ready ✅
• License: MIT

---

Get Gemini API Key

Visit: https://aistudio.google.com/apikey

Free tier includes:

• 15 requests per minute
• 1 million tokens per day
• Perfect for development!

---

Built with Axum + Rust