Summary

ccproxy enhances Claude Code by acting as a proxy, enabling seamless integration with multiple Large Language Model (LLM) providers like OpenAI, Gemini, and Perplexity. It targets users who want to optimize LLM usage by routing different types of requests—from standard coding tasks to large context windows or web searches—to the most suitable and cost-effective model. This provides significant flexibility and potential cost savings by intelligently managing LLM calls.

How It Works

ccproxy intercepts requests from Claude Code via a LiteLLM Proxy Server. It utilizes a hook-based system defined in ccproxy.yaml, including rule_evaluator and model_router hooks. Custom rules, such as TokenCountRule or MatchToolRule, dynamically label requests based on criteria like token count or tool usage. The model_router hook then uses these labels to rewrite the target model in LiteLLM's config.yaml through model aliases, directing the request to the most appropriate LLM provider before LiteLLM forwards it.

Quick Start & Requirements

Installation is recommended via uv tool install claude-ccproxy --with 'litellm[proxy]' or from GitHub (uv tool install git+https://github.com/starbased-co/ccproxy.git --with 'litellm[proxy]'). Pip installation requires both packages in the same virtual environment. A prerequisite is having LiteLLM installed alongside ccproxy. Setup involves running ccproxy install to generate configuration files (~/.ccproxy/ccproxy.yaml, ~/.ccproxy/config.yaml). The proxy is started with ccproxy start --detach, and Claude Code is configured to use http://localhost:4000 as its ANTHROPIC_BASE_URL. Further configuration details are available in docs/configuration.md.

Highlighted Details

• Intelligent Model Routing: Dynamically routes Claude Code requests to various LLM providers (e.g., OpenAI, Gemini, Perplexity) based on configurable rules.
• Rule-Based Logic: Supports routing based on token count, requested model name, tool usage (e.g., WebSearch), or a specific "thinking" flag.
• Extensible Hook System: Allows custom request processing at different stages, including rule evaluation, model routing, OAuth forwarding, and header capture.
• CLI Management: Provides commands for installation, proxy management (start, stop, status), and executing commands within the proxied environment (ccproxy run).

Maintenance & Community

Community engagement is encouraged via issues and pull requests. A Discord server is mentioned for discussion, though a direct link is not provided. Status Warning: As of early 2026, the main branch may not be stable for all Claude Code versions, with ongoing development towards a release candidate.

Licensing & Compatibility

The repository README does not explicitly state a software license, posing a significant adoption blocker, particularly for commercial use.

Limitations & Caveats

The main branch is flagged as potentially unstable for certain Claude Code versions, with active development ongoing. It requires LiteLLM and ccproxy to reside within the same Python environment, potentially complicating dependency management. The absence of a clear license is a significant adoption blocker.