cc-proxy-plugin CLAUDE.md

cc-proxy — maintainer handoff

A local HTTP proxy that lets Claude Code use GLM (Z.ai), OpenRouter, DeepSeek, Qwen, LM Studio (self-hosted, lmstudio:-selector-only), and Claude in one session. Claude Code points ANTHROPIC_BASE_URL at it; the proxy routes each request by model name and forwards. That's the whole product. Resist making it more than that.

Read next: docs/ARCHITECTURE.md (design + why), docs/OPERATIONS.md (runtime facts, debugging), docs/BACKLOG.md (open work + why past decisions went the way they did — probe matrices, measurements, refuted alternatives), CONTRIBUTING.md (add-a-provider procedure).

Gates

pnpm check (= pnpm lint && pnpm test) before any commit; CI runs the same. The suite spins real local HTTP backends — if you change forwarding and no test fails, you haven't tested it; add one.

pnpm probe:vendors is the MANUAL gate for claims about someone else's server. It is never in pnpm check (real keys, real quota) and exits 1 when a vendor stops behaving the way a source comment says it does. Run it when you touch routing/forwarding, or when a probe date in a comment looks old.

Invariants (breaking one is a design decision, not a refactor)

Each is locked by tests; the test names tell you what you broke.

1. Transparent pipe. Auth/headers only. Full inbound path including the query string reaches upstream; bodies forwarded byte-for-byte. THREE body exceptions (thinking-strip, <provider>: selector-strip, [1m] variant- suffix strip) and TWO header exceptions (hop-by-hop dropped — CL+TE together trips smuggling rejection; and the upstream's own x-request-id dropped from every forwarded response, 0.8.0 — writeHead REPLACES what setHeader put there, so a vendor that emits one took over the proxy's correlation id). The third body strip was added in 0.6.3 on a measurement, not a preference: both Z.ai and the Qwen plan 400 on a suffixed id, so forwarding CC's display spelling means routing correctly and then failing at the vendor. All three strips share one shape — a spelling the CLIENT uses that no BACKEND knows. → server.test.js "query string is preserved…", "provider selector strip…", "routing log annotates the normalized id…", "keeps the proxy's x-request-id when the upstream sets its own…" (and its two size-cap passthrough siblings — each writeHead is a separate chance to leak the vendor's id)
2. Stateless. No breakers, no on-disk state, no in-proxy waiting. Rate limits inject Retry-After and let the client back off. → "…1302 … gets a Retry-After", "1313 … no Retry-After"
3. Credential isolation. Inbound Authorization/x-api-key never reach a third party; the Claude route passes them through (OAuth). Never set ANTHROPIC_API_KEY in settings templates — it shadows OAuth. → providers.test.js "…drops an inbound x-api-key…"
4. claude-haiku-* pins to Claude so internal ops never burn paid quota. The pin tests the STRIPPED tail — pinning the raw id lets glm:claude-haiku-… skip it. → router.test.js
5. Anthropic Messages only. No OpenAI↔Anthropic translation layer, ever. The media tunnel (POST /api/v1/services/aigc/multimodal-generation/generation, 0.7.0) is NOT an exception and must not become one: it forwards a DashScope-shaped body byte-for-byte to a DashScope endpoint and returns the vendor's own response. The proxy knows neither schema; it adds the credential. An /v1/images/generations in front of every backend that can draw — the version of this that WOULD argue with the invariant — was declined. → models.test.js "media generation tunnel (issue #40)"
6. Client abort propagates upstream, or a cancelled turn bills into a dead socket. → "client abort mid-stream aborts the upstream request"
7. Loopback bind by default. PROXY_HOST is the explicit opt-out. → config.test.js