Claude Code Proxy

To run the proxy locally, you need uv installed and valid API keys for your chosen provider.

1. Clone the repository:

   git clone https://github.com/1rgs/claude-code-proxy.git
   cd claude-code-proxy

2. Install uv (if not present):

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Configure Environment Variables: Copy the example file:

   cp .env.example .env

   Edit .env with your API keys (OPENAI_API_KEY, GEMINI_API_KEY, or ANTHROPIC_API_KEY).
4. Run the server:

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

Once the proxy server is running (defaulting to port 8082), you can connect the Claude Code CLI to it by setting the ANTHROPIC_BASE_URL environment variable.

1. Install Claude Code:

   npm install -g @anthropic-ai/claude-code

2. Launch with Proxy:

   ANTHROPIC_BASE_URL=http://localhost:8082 claude

You can run the proxy using Docker Compose or a single Docker command. Ensure you have a .env file configured with your API keys before starting.

Using Docker Compose (Recommended): Create a docker-compose.yml file:

services:
  proxy:
    image: ghcr.io/1rgs/claude-code-proxy:latest
    restart: unless-stopped
    env_file: .env
    ports:
      - 8082:8082

Using Docker Run:

docker run -d --env-file .env -p 8082:8082 ghcr.io/1rgs/claude-code-proxy:latest

The proxy maps Claude models (haiku/sonnet) to other providers using environment variables. Use these keys in your .env file:

• PREFERRED_PROVIDER: Set to openai (default), google, or anthropic.
• BIG_MODEL: The model to map sonnet requests to.
  • If openai: defaults to gpt-4.1.
  • If google: defaults to gemini-2.5-pro-preview-03-25.
• SMALL_MODEL: The model to map haiku requests to.
  • If openai: defaults to gpt-4.1-mini.
  • If google: defaults to gemini-2.0-flash.

Mapping Logic:

• openai: haiku/sonnet $\rightarrow$ openai/[SMALL_MODEL] / openai/[BIG_MODEL].
• google: haiku/sonnet $\rightarrow$ gemini/[SMALL_MODEL] / gemini/[BIG_MODEL] (if in known Gemini list, else fallback to OpenAI).
• anthropic: Requests are passed directly to Anthropic with anthropic/ prefix (ignores BIG_MODEL/SMALL_MODEL).

If you want to use Google Gemini via Vertex AI using Application Default Credentials (ADC) instead of a static API key, configure the following in your .env:

• PREFERRED_PROVIDER=google
• USE_VERTEX_AUTH=true
• VERTEX_PROJECT: Your Google Cloud Project ID.
• VERTEX_LOCATION: The Google Cloud region (e.g., us-central1).

The proxy automatically maps Anthropic model names to other providers based on your configuration:

1. Haiku Models: Mapped to SMALL_MODEL. If PREFERRED_PROVIDER is google, it maps to gemini/{SMALL_MODEL}, otherwise to openai/{SMALL_MODEL}.
2. Sonnet Models: Mapped to BIG_MODEL. If PREFERRED_PROVIDER is google, it maps to gemini/{BIG_MODEL}, otherwise to openai/{BIG_MODEL}.
3. Explicit Prefixes: If a model name already starts with openai/, gemini/, or anthropic/, it is used as-is.
4. Known Models: If a model name matches a known Gemini or OpenAI model but lacks a prefix, the appropriate prefix is added.

The proxy server is executed using uvicorn.run. To minimize log noise in the console, it is configured to run on host 0.0.0.0, port 8082, with the log_level set to error.

uvicorn.run(app, host="0.0.0.0", port=8082, log_level="error")

The proxy automatically applies prefixes to model names.

OpenAI Models (prefixed with openai/):

• o3-mini, o1, o1-mini, o1-pro, gpt-4.5-preview, gpt-4o, gpt-4o-audio-preview, chatgpt-4o-latest, gpt-4o-mini, gpt-4o-mini-audio-preview, gpt-4.1, gpt-4.1-mini

Gemini Models (prefixed with gemini/):

• gemini-2.5-pro, gemini-2.5-flash

The /v1/messages endpoint allows you to send Anthropic-formatted requests to the proxy. The proxy converts these requests to LiteLLM format and routes them to the appropriate provider (OpenAI, Gemini/Vertex AI, or Anthropic) based on the model prefix.

Model Routing Logic:

• openai/*: Uses OPENAI_API_KEY and optionally OPENAI_BASE_URL.
• gemini/*: Uses GEMINI_API_KEY or Vertex AI credentials if USE_VERTEX_AUTH is enabled.
• anthropic/*: Uses ANTHROPIC_API_KEY.

Special Handling for OpenAI Models: Because OpenAI does not support Anthropic's complex content block structure (e.g., lists of text/tool blocks), the proxy automatically flattens content blocks into plain text strings for OpenAI requests. This includes converting tool_result and tool_use blocks into descriptive text to ensure compatibility.

Use the /v1/messages/count_tokens endpoint to estimate the number of input tokens for a given set of messages. The proxy converts the Anthropic-style request to a LiteLLM-compatible format and uses LiteLLM's token_counter to return the result.

Returns: A TokenCountResponse containing the input_tokens count.

A simple health check endpoint that returns a JSON object confirming the proxy is running.

{
  "message": "Anthropic Proxy for LiteLLM"
}