English | 简体中文

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 backend 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.

• ⛓️ N-tier Chained Failover: Automatically downgrades from official Claude Plans, gracefully falling back to GitHub Copilot, then Google Antigravity, with Zhipu GLM acting as the ultimate safety net.
• 🛡️ Smart Resilience & Quota Guardians: Every single backend 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. 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.

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

git clone https://github.com/ThreeFish-AI/coding-proxy
cd coding-proxy
uv sync

cp config.example.yaml config.yaml
# Use environment variables to defensively inject your keys
export ZHIPU_API_KEY="your-api-key-here"

coding-proxy start
#  INFO:     Started server process
#  INFO:     Uvicorn running on http://127.0.0.1:8046 (Press CTRL+C to quit)

Open a fresh terminal tab, point to the proxy server when firing up Claude Code, and enjoy blissful, uninterrupted coding nirvana:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8046
claude

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

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 TD
    Client["Claude Code Client"]
    Server["FastAPI Server<br/><code>server/app.py</code>"]
    Router["RequestRouter<br/><code>routing/router.py</code>"]

    Client -->|"POST /v1/messages"| Server
    Server --> Router

    Router --> T0
    Router --> T1
    Router --> T2
    Router --> TN

    subgraph T0["Tier 0: Claude Plans"]
        direction LR
        A_BE["AnthropicBackend"]
        A_CB["CB (Circuit Breaker)"]
        A_QG["QG (Quota Guard)"]
    end

    subgraph T1["Tier 1: GitHub Copilot"]
        direction LR
        C_BE["CopilotBackend"]
        C_CB["CB (Circuit Breaker)"]
        C_QG["QG (Quota Guard)"]
    end

    subgraph T2["Tier 2: Google Antigravity"]
        direction LR
        G_BE["AntigravityBackend"]
        G_CB["CB (Circuit Breaker)"]
        G_QG["QG (Quota Guard)"]
    end

    subgraph TN["Tier N: Zhipu (Safety Net)"]
        Z_BE["ZhipuBackend"]
    end

    A_BE --> API_A["Anthropic API"]
    C_BE --> API_C["GitHub Copilot API"]
    G_BE --> API_G["Google Gemini API"]
    Z_BE --> API_Z["Zhipu GLM API"]

    style T0 fill:#1a5276,color:#fff
    style T1 fill:#1a5276,color:#fff
    style T2 fill:#1a5276,color:#fff
    style TN fill:#7b241c,color:#fff

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

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 backends. (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.

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.