Skip to main content

English | 简体中文

coding-proxy coding-proxy

A High-Availability, Transparent, and Smart Multi-Vendor Proxy for Claude Code

Python Version License Package Manager Architecture


💡 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"
## ...or store the key encrypted in the config store (never echoed back)
# echo -n "sk-..." | uv run coding-proxy config set-secret vendors.zhipu.api_key --stdin

# Start coding-proxy with the stored configuration
# Runtime config lives in ~/.coding-proxy/config.db (SQLite, secrets encrypted);
# edit it via the Dashboard → Config page or the `coding-proxy config` CLI — no YAML to manage.
# An existing ~/.coding-proxy/config.yaml from older versions is imported once on first start.
uv run coding-proxy start

## Use the `-c` flag to import a legacy YAML as the one-time migration source
# 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 Config tab edits the whole configuration online (vendors, tiers, failover, model mapping, pricing, native API, session policies) — saves hot-swap the running proxy with zero restarts. Unlock it once with the admin token printed by coding-proxy config token.


🛠️ The CLI Console Guide

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

Command Description Example Usage
start Fire up the proxy server. Supports custom ports and a one-time legacy YAML import via -c. coding-proxy start -p 8080
config Manage the config store (~/.coding-proxy/config.db). Sub-commands: set, reset, set-secret (encrypted keys), import/export, token. coding-proxy config set vendors.zhipu.timeout_ms 60000
auth Manage OAuth credentials. Sub-commands: login (browser OAuth), status (token validity), reauth (re-authenticate), logout (clear tokens). coding-proxy auth login -p github
status Check proxy health. Shows circuit breaker states (OPEN/CLOSED) and quota status across all tiers. coding-proxy status
usage Token Stats Dashboard. Stalks every single token consumed, failovers triggered, and latency across day/vendor/model dimensions. coding-proxy usage -d 7 -v anthropic
reset The emergency flush button. Force-reset all circuit breakers and quotas instantly when you've confirmed the main vendor is back from the dead. coding-proxy reset

📐 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 setup to the semantic breakdown of every config 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)

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

Built with 🧠, ❤️, and an absurd amount of coffee by ThreeFish-AI · Released under the Apache License 2.0.

Metadata

Release files for coding-proxy 0.6.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coding-proxy 0.6.4
File Size Uploaded Provenance Actions
coding_proxy-0.6.4.tar.gz 2.3 MB With provenance Details for coding_proxy-0.6.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for coding-proxy 0.6.4
File Interpreter ABI Platform Actions
coding_proxy-0.6.4-py3-none-any.whl Python 3 none any Details for coding_proxy-0.6.4-py3-none-any.whl

Total release size: 2.7 MB

Release files / coding_proxy-0.6.4.tar.gz

Download URL coding_proxy-0.6.4.tar.gz
Size 2.3 MB
Tags Source
SHA-256 checksum
How to use checksums
292cf1215a07f961ff094598c54ccf09bfe9ebc80d8b87293c3a160da063d29d
BLAKE2b-256 checksum
How to use checksums
7bf682fed5972635ece0239ff9fba27d144d3a8913702b1d8692457b2ea16737
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / coding_proxy-0.6.4-py3-none-any.whl

Download URL coding_proxy-0.6.4-py3-none-any.whl
Size 408.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2e65bf40cd7b274a029f2cf0d784ba994c3ec041057e8b3f1820c313f41d57fd
BLAKE2b-256 checksum
How to use checksums
9f31c73b1531d2d435a62b9893e50087b0a2261c7aab14ec74a5faad567563e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for coding-proxy 0.6.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for coding_proxy-0.6.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page