{"id":30717877,"url":"https://github.com/jiafuei/cc-proxy","last_synced_at":"2026-05-18T19:36:35.121Z","repository":{"id":311628470,"uuid":"1043762912","full_name":"jiafuei/cc-proxy","owner":"jiafuei","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-01T16:10:28.000Z","size":708,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-01T18:15:10.212Z","etag":null,"topics":["claude-code"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jiafuei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-24T15:12:25.000Z","updated_at":"2025-09-01T16:10:31.000Z","dependencies_parsed_at":"2025-08-25T17:24:08.461Z","dependency_job_id":"9350401e-9ec3-4f2e-bfcb-028956379f93","html_url":"https://github.com/jiafuei/cc-proxy","commit_stats":null,"previous_names":["jiafuei/cc-proxy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jiafuei/cc-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiafuei%2Fcc-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiafuei%2Fcc-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiafuei%2Fcc-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiafuei%2Fcc-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jiafuei","download_url":"https://codeload.github.com/jiafuei/cc-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiafuei%2Fcc-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273417342,"owners_count":25101817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code"],"created_at":"2025-09-03T09:02:22.490Z","updated_at":"2026-05-18T19:36:35.113Z","avatar_url":"https://github.com/jiafuei.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-proxy 🚀\r\n\r\n**A friendly proxy that makes Claude Code work with any AI provider**\r\n\r\nTransform 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.\r\n\r\n## What is cc-proxy?\r\n\r\ncc-proxy sits between Claude Code and AI providers, translating requests and responses on-the-fly. Instead of being locked into one provider, you can:\r\n\r\n- **Route to different models** for different tasks (fast models for quick work, powerful models for complex problems)\r\n- **Use any provider** - OpenAI, custom endpoints, local models, or even multiple providers simultaneously  \r\n- **Transform requests** - add authentication, modify prompts, or inject custom behavior\r\n- **Stay in Claude Code** - no need to switch tools or learn new interfaces\r\n\r\nPerfect for developers who want flexibility without sacrificing the Claude Code experience they love.\r\n\r\n## Setup \u0026 Installation\r\n\r\n### Prerequisites\r\n- **Python 3.11+** (Python 3.12 recommended)\r\n- **uv** for package management (or pip if you prefer)\r\n\r\n### Quick Setup\r\n\r\n1. **Clone and install**\r\n   ```bash\r\n   git clone https://github.com/your-username/cc-proxy.git\r\n   cd cc-proxy\r\n   uv sync\r\n   ```\r\n\r\n2. **Set up configuration directories**\r\n   ```bash\r\n   mkdir -p ~/.cc-proxy\r\n   cp config.example.yaml ~/.cc-proxy/config.yaml\r\n   cp user.example.yaml ~/.cc-proxy/user.yaml\r\n   ```\r\n\r\n3. **Configure your API keys**\r\n   ```bash\r\n   # Add to your shell profile (.bashrc, .zshrc, etc.)\r\n   export ANTHROPIC_API_KEY=\"your-anthropic-key\"\r\n   export OPENAI_API_KEY=\"your-openai-key\"  # if using OpenAI\r\n   ```\r\n\r\n4. **Start the proxy**\r\n   ```bash\r\n   uv run python -m app.main\r\n   ```\r\n\r\n   You should see: `✅ Server running at http://127.0.0.1:8000`\r\n\r\n5. **Test it works**\n   ```bash\n   # New Claude-prefixed endpoint (preferred)\n   curl -X POST \"http://127.0.0.1:8000/claude/v1/messages\" \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: Bearer dummy-key\" \\\n     -d '{\"model\": \"sonnet\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}], \"max_tokens\": 100}'\n\n   # Legacy endpoint still available for existing Claude Code clients\n   curl -X POST \"http://127.0.0.1:8000/v1/messages\" -d '...'\n   ```\n\r\n## Key Features\r\n\r\n### 🔄 **Universal Provider Support**\r\nConnect to any AI provider with built-in transforms for OpenAI, Anthropic, and custom endpoints. No more vendor lock-in.\r\n\r\n### 🧠 **Smart Model Routing** \r\nAutomatically route different types of requests to different models:\r\n- Planning tasks → Your most capable model\r\n- Quick responses → Fast, cost-effective models  \r\n- Background tasks → Specialized or cheaper models\r\n\r\n### 🔧 **Flexible Transformations**\r\n- **Request transforms**: Add authentication, modify prompts, inject context, merge tool calls\r\n- **Response transforms**: Normalize outputs, add metadata, apply filters, clean system messages\r\n- **Smart routing**: Subagent routing with intelligent message handling\r\n- **Custom plugins**: Write your own transformers in Python\r\n- **Software Engineering Mode**: Specialized system message for coding tasks\r\n\r\n### 📦 **Drop-in Replacement**\r\nPoint Claude Code at `http://localhost:8000` and everything just works. No configuration changes needed in Claude Code itself.\r\n\r\n### 🎯 **Composable Pipelines** \r\nChain multiple transformers together for complex workflows. Each step is configurable and can be enabled/disabled per provider.\r\n\r\n## Configuration\r\n\r\ncc-proxy uses two configuration files:\n\r\n### Server Configuration (`~/.cc-proxy/config.yaml`)\r\nBasic server settings - host, port, logging, CORS, etc. Most users can use the defaults.\r\n\r\n### User Configuration (`~/.cc-proxy/user.yaml`)\r\nYour providers, models, and routing rules. This is where the magic happens:\r\n\r\n```yaml\ntransformer_paths:\n  - '~/cc-proxy/plugins'\n\nproviders:\n  - name: 'anthropic-provider'\n    base_url: 'https://api.anthropic.com'\n    api_key: !env ANTHROPIC_API_KEY\n    type: 'anthropic'\n    capabilities:\n      - 'messages'\n      - 'count_tokens'\n\n  - name: 'openai-chat'\n    base_url: 'https://api.openai.com'\n    api_key: !env OPENAI_API_KEY\n    type: 'openai'\n    capabilities:\n      - 'messages'\n\n  - name: 'openai-responses'\n    base_url: 'https://api.openai.com'\n    api_key: !env OPENAI_API_KEY\n    type: 'openai-responses'\n    capabilities:\n      - 'responses'\n\nmodels:\n  - alias: 'sonnet'\n    id: 'claude-3-5-sonnet-20241022'\n    provider: 'anthropic-provider'\n  - alias: 'gpt4'\n    id: 'gpt-4o'\n    provider: 'openai-chat'\n  - alias: 'codex-openai'\n    id: 'gpt-4o-mini'\n    provider: 'openai-responses'\n\nrouting:\n  default: 'sonnet'\n  builtin_tools: 'gpt4'\n  planning: 'gpt4'\n  background: 'haiku'\n  thinking: 'gpt4'\n```\n\r\nBuilt-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.\n\r\n## Usage with Claude Code\r\n\r\n1. **Start cc-proxy** (if not already running)\n   ```bash\n   uv run fastapi dev  # autoreload during development\n   ```\n\r\n2. **Configure Claude Code** to use the proxy\r\n   - Set API endpoint to: `http://localhost:8000`\r\n   - Use any dummy API key (cc-proxy handles real authentication)\r\n\r\n3. **Use Claude Code normally**\r\n   - Your requests will be automatically routed based on your configuration\r\n   - Different request types can go to different models\r\n   - All responses come back in Claude format\r\n\r\nThat's it! Claude Code works exactly the same, but now with all the flexibility of cc-proxy.\r\n\r\n## Advanced Configuration\r\n\r\n### Custom Providers\n```yaml\nproviders:\n  - name: 'my-custom-api'\n    api_key: !env CUSTOM_API_KEY\n    base_url: 'https://my-api.example.com'\n    type: 'openai-responses'\n    capabilities:\n      - 'responses'\n    transformers:\n      codex:\n        request:\n          - class: 'my_transformers.CustomAuthTransformer'\n            params: {special_header: 'custom-value'}\n```\n\n### Multiple Model Routing\n```yaml\r\nrouting:\r\n  default: 'sonnet'           # Most requests\r\n  builtin_tools: 'sonnet'     # Built-in tools (WebSearch, WebFetch, etc.) - highest priority\r\n  thinking: 'o1'              # Complex reasoning\r\n  planning: 'gpt4'            # Planning mode\r\n  background: 'haiku'         # Quick tasks\r\n  plan_and_think: 'sonnet'    # Planning + thinking\r\n```\r\n\r\n### Custom Transformers\nPlace Python files in directories listed in `transformer_paths` and reference them by `module.ClassName`.\n\n#### Built-in Tools Support\nCC-Proxy automatically converts Anthropic's built-in tools (WebSearch, WebFetch) to provider-specific formats:\n\nNo extra configuration is required—the OpenAI and Gemini defaults ship with the\nnecessary transformers. When a Claude request includes built-in tools, cc-proxy\nautomatically converts them and forwards the appropriate authentication.\n\n**WebSearch Conversion**:\n- Anthropic `web_search` tool → OpenAI `web_search_options` parameter\r\n- Domain filters (`allowed_domains`, `blocked_domains`) mapped correctly\r\n- User location parameters converted to OpenAI format\r\n- Model automatically upgraded to search-preview variants\r\n- Response annotations converted back to Anthropic format\r\n\r\n## Technical Details\r\n\r\n### Architecture\r\n- **FastAPI server** with async request handling\r\n- **Pluggable transformer system** for request/response modification\r\n- **Provider abstraction** supporting HTTP and streaming protocols\r\n- **Configuration-driven routing** with environment variable support\r\n- **Comprehensive logging** and debugging tools\r\n\r\n### API Compatibility\r\n- **OpenAI Chat Completions** - Automatic format conversions\r\n- **Streaming support** - Real-time response streaming\r\n- **Subagent routing** - Advanced routing capabilities for complex workflows\r\n\r\n### Development Commands\n```bash\n# Lint and format\nuvx ruff check --fix \u0026\u0026 uvx ruff format .\n\n# Start development server with autoreload\nuv run fastapi dev\n\n# Manual smoke test (Claude channel)\ncurl -X POST http://127.0.0.1:8000/claude/v1/messages -H 'Content-Type: application/json' \\\n  -d '{\"model\": \"sonnet\", \"messages\": [{\"role\": \"user\", \"content\": \"ping\"}]}'\n```\n\r\n## Contributing \u0026 Support\r\n\r\n### Getting Help\r\n- **Issues**: Report bugs or request features on GitHub\r\n- **Discussions**: Ask questions or share configurations\r\n- **Documentation**: Check example configs and inline comments\r\n\r\n### Contributing\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Document manual verification steps (or add new automated coverage once the post-migration harness lands)\n4. Run linting: `uvx ruff check --fix \u0026\u0026 uvx ruff format .`\n5. Submit a pull request\n\r\n### Acknowledgments\r\nInspired by [ccflare](https://github.com/snipeship/ccflare) and [claude-code-router](https://github.com/musistudio/claude-code-router). Built with FastAPI, httpx, and lots of ☕.\r\n\r\n---\r\n\r\n**Ready to supercharge your Claude Code experience?** Start with the Quick Setup above and explore the possibilities! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiafuei%2Fcc-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiafuei%2Fcc-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiafuei%2Fcc-proxy/lists"}