English | 简体中文

💡 Why Do We Even Need coding-proxy?

When you're deeply immersed in your coding "zone" with Claude Code (or any AI assistant relying on Anthropic's Messages API), there's nothing quite as soul-crushing as having your flow violently interrupted by:

• 🛑 Rate Limiting: High-frequency pings trigger the dreaded 429 rate_limit_error. Forced to stare at the screen and rethink your life choices.
• 💸 Usage Cap: Aggressive code generation drains your daily/monthly quota, slamming you with a cold, heartless 403 error.
• 🌋 Overloaded Servers: Anthropic's official servers melt down during peak hours, tossing back a merciless 503 overloaded_error.

coding-proxy was forged in the developer fires to terminate these exact pain points. Serving as a purely transparent intermediate layer, it blesses your Claude Code with millisecond-level "N-tier chained fallback disaster recovery." When your primary vendor goes belly up, it seamlessly and instantly switches your requests to the next smartest available fallback (like GitHub Copilot, Google Antigravity, or even Zhipu GLM)—with zero manual intervention, and zero perceived interruption.

🌟 Core Features

• ⛓️ N-tier Chained Failover: Autonomous descending sequence, supporting Claude's official plans, as well as Coding Plans from GitHub Copilot, Google Antigravity, Z AI, MiniMax, Alibaba Qwen, Xiaomi, Kimi, Doubao, etc.
• 🛡️ Smart Resilience & Quota Guardians: Every single vendor node comes fully armed with an independent Circuit Breaker and Quota Guard to proactively dodge avalanches without breaking a sweat.
• 👻 Phantom-like Transparency: 100% transparent to the client! No code tweaks required. Overwrite ANTHROPIC_BASE_URL with a single line, and you're good to go.
• 🔄 Universal Alchemy (Formats & Models): Native support for two-way request/streaming (SSE) translations between Anthropic ←→ Gemini and Anthropic ←→ OpenAI. Plus, auto/DIY model name mapping (e.g., effortlessly morphing claude-* into glm-*).
• 📊 Extreme Observability: Built-in, zero-BS local monitoring powered by a SQLite WAL. The CLI provides a one-click detailed Token usage dashboard (coding-proxy usage).
• ⚡ Featherweight Standalone Deployment: A fully asynchronous architecture (FastAPI + httpx). Zero dependency on Redis, message queues, or other heavy machinery—absolutely no extra baggage for your dev rig.

🚀 Quick Start

1. Prerequisite Checks

Make sure your rig has Python 3.12+ and the uv package manager installed (highly recommended, because life is too short for slow package managers).

2. Lightning Install

uv add coding-proxy

3. Ignite the Proxy Server

## (Optional) Highly recommended to enable Zhipu GLM. Use env vars to defensively inject your keys
# export ZHIPU_API_KEY="your-api-key-here"

# Start coding-proxy with the default configuration
# The default config lives at: ~/.coding-proxy/config.yaml.
uv run coding-proxy start

## Use the `-c` flag to gracefully point to a custom config path
# uv run coding-proxy start -c ./coding-proxy.yaml

# INFO:     Started server process [1403]
# INFO:     Waiting for application startup.
# ...
# INFO:     coding-proxy started: host=127.0.0.1 port=3392
# INFO:     Application startup complete.
# INFO:     Uvicorn running on http://127.0.0.1:3392 (Press CTRL+C to quit)

4. Seamless Claude Code Integration

Open a fresh terminal tab and route your traffic through coding-proxy before firing up Claude Code:

export ANTHROPIC_BASE_URL=http://127.0.0.1:3392

# Enjoy blissful, silky-smooth, and uninterrupted coding nirvana:
claude

5. Peek at the Dashboard

Curious about your real-time token spend, latency, and circuit breaker pulse? Pop open your browser and head to:

open http://127.0.0.1:3392/dashboard

🛠️ The CLI Console Guide

coding-proxy comes equipped with a badass suite of CLI tools to help you boss around your proxy state.

📐 Architectural Panorama

When a request inevitably hits the fan, the RequestRouter slides gracefully down the N-tier tree, juggling circuit breakers and token quotas to decide the ultimate destination:

graph RL
    %% 样式定义 (支持明暗双色模式的高对比色彩)
    classDef client fill:#1E3A8A,stroke:#60A5FA,stroke-width:2px,color:#EFF6FF,rx:8,ry:8
    classDef router fill:#4C1D95,stroke:#A78BFA,stroke-width:2px,color:#F5F3FF,rx:8,ry:8
    classDef gateway fill:#7C2D12,stroke:#FB923C,stroke-width:2px,color:#FFF7ED
    classDef api fill:#14532D,stroke:#4ADE80,stroke-width:2px,color:#F0FDF4
    classDef fallback fill:#27272A,stroke:#A1A1AA,stroke-width:2px,color:#F4F4F5

    Client["💻<br/>Client (Claude Code)"]:::client

    subgraph CodingProxy["⚡ coding-proxy"]
        direction RL

        Router["RequestRouter<br/><code>routing/router.py</code>"]:::router

        Router -->NTier

        subgraph NTier["N-tier"]
            direction TB

            subgraph Tier0 ["Tier 0: Zhipu"]
                direction RL
                G0{"CB / Quota"}:::gateway -- "✅ Pass" --> API0(("GLM API")):::api
            end

            subgraph Tier1 ["Tier 1: Anthropic"]
                direction RL
                G1{"CB / Quota"}:::gateway -- "✅ Pass" --> API1(("Anthropic API")):::api
            end

            subgraph Tier2 ["Tier 2: GitHub Copilot"]
                direction RL
                G2{"CB / Quota"}:::gateway -- "✅ Pass" --> API2(("Copilot API")):::api
            end

            subgraph Tier3 ["Tier 3: Google Antigravity"]
                direction RL
                API3(("Gemini API")):::fallback
            end

            Tier0 -. "❌ Blocked / API Error" .-> Tier1
            Tier1 -. "❌ Blocked / API Error" .-> Tier2
            Tier2 -. "🆘 Safety Net Downgrade" .-> Tier3
        end

    end

    Client -->|"POST /v1/messages"| CodingProxy

For a deep dive into the architecture and under-the-hood wizardry, consult framework.md (Currently in Chinese).

📚 Detailed Documentation Map

To ensure this project outlives us all (long-term maintainability), we offer exhaustive, Evidence-Based documentation:

• 📖 User Guide — From installation and bare-minimum configs to the semantic breakdown of every config.yaml field and common troubleshooting manuals. (Currently in Chinese)
• 🏗️ Architecture Framework — A meticulous decoding of underlying design patterns (Template Method, Circuit Breaker, State Machine, etc.), targeted at devs who want to peek into the matrix or contribute new vendors. (Currently in Chinese)
• 🤝 Engineering Guidelines (AGENTS.md) — The systemic context mindset and AI Agent collaboration protocol. It preaches refactoring, reuse, and orthogonal abstractions and serves as the ultimate guiding light for all development in this repository.

💡 Inspiration & Acknowledgements

During our chaotic yet rewarding exploration of engineering practices, we were heavily inspired by cutting-edge tech ecosystems and brilliant designs. Special shoutouts:

• A massive thank you to Claude Code for sparking our obsession with crafting the ultimate, seamless programming assistant experience.
• Endless gratitude to the open-source community's myriad of API Proxy projects. Your trailblazing in reverse proxies, high-availability setups (circuit breakers/streaming proxies), and dynamic routing provided the rock-solid theoretical foundation for coding-proxy's elastic N-Tier mechanisms.