cc-proxy-plugin: Instructions file for Claude Code

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 is the whole product. Resist making it more than that.

This file carries the rules. The evidence behind each rule (measurements, histories, refuted alternatives) is in docs/MAINTAINING.md; read the matching section there before reversing anything here.

Read next: docs/ARCHITECTURE.md (design and why), docs/ROUTING.md / docs/DISCOVERY.md / docs/CONFIGURATION.md (the user-facing contracts), docs/OPERATIONS.md (runtime), docs/RELEASING.md, docs/BACKLOG.md (open work and why past decisions went the way they did), 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 have not tested it. Add one.
• pnpm probe:vendors is the MANUAL gate for claims about someone else's server. Never in pnpm check (real keys, real quota). It exits 1 when a vendor stops behaving the way a source comment says. Run it when you touch routing or forwarding, or when a probe date in a comment looks old.
• Node 22 or newer. .npmrc is engine-strict because process.loadEnvFile is how ~/.env is read.

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 and headers only. The full inbound path including the query string reaches upstream; bodies forwarded byte for byte. Four body exceptions and two header exceptions (hop-by-hop dropped; the upstream's own x-request-id dropped, because writeHead replaces what setHeader put there). The first three body strips share one shape — a spelling the CLIENT uses that no BACKEND knows: thinking-strip, <provider>: selector strip, [1m] suffix strip. The fourth is the INVERSE shape — history a BACKEND produced that the destination backend rejects wholesale (GLM's own server_tool_use calls) — and is DIRECTIONAL for that reason: claude route only, since the same history is legal input to the backend that made it. It removes MESSAGES too, not just blocks, because content: [] is its own 400. → 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…", "no message reaches upstream with an EMPTY content array"
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 a settings template; it shadows OAuth. → providers.test.js "…drops an inbound x-api-key…"
4. claude-haiku-* pins to Claude. 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-to-Anthropic translation, ever. The media tunnel forwards a DashScope body byte for byte and is not an exception. → 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; PROXY_AUTH_TOKEN makes it safe. → config.test.js
8. One bad request never ends the process. No uncaughtException handler exists; every dispatch point contains its own throws (a JSON null body used to exit the process for every session). → server.test.js "dispatcher containment (a bad request never ends the process)"