cc-proxy 🚀

A friendly proxy that makes Claude Code work with any AI provider

Transform Claude Code into a universal AI client by routing requests to OpenAI, custom providers, or even multiple models simultaneously. Think of it as a smart translator that speaks every AI API dialect.

What is cc-proxy?

cc-proxy sits between Claude Code and AI providers, translating requests and responses on-the-fly. Instead of being locked into one provider, you can:

• Route to different models for different tasks (fast models for quick work, powerful models for complex problems)
• Use any provider - OpenAI, custom endpoints, local models, or even multiple providers simultaneously
• Transform requests - add authentication, modify prompts, or inject custom behavior
• Stay in Claude Code - no need to switch tools or learn new interfaces

Perfect for developers who want flexibility without sacrificing the Claude Code experience they love.

Setup & Installation

Prerequisites

• Python 3.11+ (Python 3.12 recommended)
• uv for package management (or pip if you prefer)

Quick Setup

1. Clone and install

   git clone https://github.com/your-username/cc-proxy.git
   cd cc-proxy
   uv sync

2. Set up configuration directories

   mkdir -p ~/.cc-proxy
   cp config.example.yaml ~/.cc-proxy/config.yaml
   cp user.example.yaml ~/.cc-proxy/user.yaml

3. Configure your API keys

   # Add to your shell profile (.bashrc, .zshrc, etc.)
   export ANTHROPIC_API_KEY="your-anthropic-key"
   export OPENAI_API_KEY="your-openai-key"  # if using OpenAI

4. Start the proxy

   uv run python -m app.main

   You should see: ✅ Server running at http://127.0.0.1:8000

5. Test it works

   # New Claude-prefixed endpoint (preferred)
   curl -X POST "http://127.0.0.1:8000/claude/v1/messages" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer dummy-key" \
     -d '{"model": "sonnet", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 100}'
   
   # Legacy endpoint still available for existing Claude Code clients
   curl -X POST "http://127.0.0.1:8000/v1/messages" -d '...'

Key Features

🔄 Universal Provider Support

Connect to any AI provider with built-in transforms for OpenAI, Anthropic, and custom endpoints. No more vendor lock-in.

🧠 Smart Model Routing

Automatically route different types of requests to different models:

• Planning tasks → Your most capable model
• Quick responses → Fast, cost-effective models
• Background tasks → Specialized or cheaper models

🔧 Flexible Transformations

• Request transforms: Add authentication, modify prompts, inject context, merge tool calls
• Response transforms: Normalize outputs, add metadata, apply filters, clean system messages
• Smart routing: Subagent routing with intelligent message handling
• Custom plugins: Write your own transformers in Python
• Software Engineering Mode: Specialized system message for coding tasks

📦 Drop-in Replacement

Point Claude Code at http://localhost:8000 and everything just works. No configuration changes needed in Claude Code itself.

🎯 Composable Pipelines

Chain multiple transformers together for complex workflows. Each step is configurable and can be enabled/disabled per provider.

Configuration

cc-proxy uses two configuration files:

Server Configuration (~/.cc-proxy/config.yaml)

Basic server settings - host, port, logging, CORS, etc. Most users can use the defaults.

User Configuration (~/.cc-proxy/user.yaml)

Your providers, models, and routing rules. This is where the magic happens:

transformer_paths:
  - '~/cc-proxy/plugins'

providers:
  - name: 'anthropic-provider'
    base_url: 'https://api.anthropic.com'
    api_key: !env ANTHROPIC_API_KEY
    type: 'anthropic'
    capabilities:
      - 'messages'
      - 'count_tokens'

  - name: 'openai-chat'
    base_url: 'https://api.openai.com'
    api_key: !env OPENAI_API_KEY
    type: 'openai'
    capabilities:
      - 'messages'

  - name: 'openai-responses'
    base_url: 'https://api.openai.com'
    api_key: !env OPENAI_API_KEY
    type: 'openai-responses'
    capabilities:
      - 'responses'

models:
  - alias: 'sonnet'
    id: 'claude-3-5-sonnet-20241022'
    provider: 'anthropic-provider'
  - alias: 'gpt4'
    id: 'gpt-4o'
    provider: 'openai-chat'
  - alias: 'codex-openai'
    id: 'gpt-4o-mini'
    provider: 'openai-responses'

routing:
  default: 'sonnet'
  builtin_tools: 'gpt4'
  planning: 'gpt4'
  background: 'haiku'
  thinking: 'gpt4'

Built-in defaults now bridge Claude ↔ OpenAI/Gemini and inject API keys from your provider config, so you only need to add transformers when you want custom behavior. See the example files for complete configuration options with detailed comments, including additional Codex aliases, custom transformer overrides, and more capability combinations.

Usage with Claude Code

1. Start cc-proxy (if not already running)

   uv run fastapi dev  # autoreload during development

2. Configure Claude Code to use the proxy

   • Set API endpoint to: http://localhost:8000
   • Use any dummy API key (cc-proxy handles real authentication)

3. Use Claude Code normally

   • Your requests will be automatically routed based on your configuration
   • Different request types can go to different models
   • All responses come back in Claude format

That's it! Claude Code works exactly the same, but now with all the flexibility of cc-proxy.

Advanced Configuration

Custom Providers

providers:
  - name: 'my-custom-api'
    api_key: !env CUSTOM_API_KEY
    base_url: 'https://my-api.example.com'
    type: 'openai-responses'
    capabilities:
      - 'responses'
    transformers:
      codex:
        request:
          - class: 'my_transformers.CustomAuthTransformer'
            params: {special_header: 'custom-value'}

Multiple Model Routing

routing:
  default: 'sonnet'           # Most requests
  builtin_tools: 'sonnet'     # Built-in tools (WebSearch, WebFetch, etc.) - highest priority
  thinking: 'o1'              # Complex reasoning
  planning: 'gpt4'            # Planning mode
  background: 'haiku'         # Quick tasks
  plan_and_think: 'sonnet'    # Planning + thinking

Custom Transformers

Place Python files in directories listed in transformer_paths and reference them by module.ClassName.

Built-in Tools Support

CC-Proxy automatically converts Anthropic's built-in tools (WebSearch, WebFetch) to provider-specific formats:

No extra configuration is required—the OpenAI and Gemini defaults ship with the necessary transformers. When a Claude request includes built-in tools, cc-proxy automatically converts them and forwards the appropriate authentication.

WebSearch Conversion:

• Anthropic web_search tool → OpenAI web_search_options parameter
• Domain filters (allowed_domains, blocked_domains) mapped correctly
• User location parameters converted to OpenAI format
• Model automatically upgraded to search-preview variants
• Response annotations converted back to Anthropic format

Technical Details

Architecture

• FastAPI server with async request handling
• Pluggable transformer system for request/response modification
• Provider abstraction supporting HTTP and streaming protocols
• Configuration-driven routing with environment variable support
• Comprehensive logging and debugging tools

API Compatibility

• OpenAI Chat Completions - Automatic format conversions
• Streaming support - Real-time response streaming
• Subagent routing - Advanced routing capabilities for complex workflows

Development Commands

# Lint and format
uvx ruff check --fix && uvx ruff format .

# Start development server with autoreload
uv run fastapi dev

# Manual smoke test (Claude channel)
curl -X POST http://127.0.0.1:8000/claude/v1/messages -H 'Content-Type: application/json' \
  -d '{"model": "sonnet", "messages": [{"role": "user", "content": "ping"}]}'

Contributing & Support

Getting Help

• Issues: Report bugs or request features on GitHub
• Discussions: Ask questions or share configurations
• Documentation: Check example configs and inline comments

Contributing

1. Fork the repository
2. Create a feature branch
3. Document manual verification steps (or add new automated coverage once the post-migration harness lands)
4. Run linting: uvx ruff check --fix && uvx ruff format .
5. Submit a pull request

Acknowledgments

Inspired by ccflare and claude-code-router. Built with FastAPI, httpx, and lots of ☕.

---

Ready to supercharge your Claude Code experience? Start with the Quick Setup above and explore the possibilities! 🚀