English | Русский

life-support

Your gateway stops breathing. This breathes for it.

A local HTTP proxy between Claude Code and Anthropic-compatible gateways (e.g. agentrouter.org / New API) that do not forward event: ping during long thinking pauses. Claude Code's stream-idle watchdog (~18s without a single byte — measured) then kills the stream and retries in an endless loop ("Waiting for API response · will retry in ...").

The proxy fixes this four ways:

1. Ping injection — when the gateway is silent for longer than IDLE_MS, the proxy sends the client a real event: ping, the same event the upstream API emits during long pauses, so the client is built to accept it as a sign of life. A complete event may only be written at an event boundary: if the gateway stalled halfway through one, the proxy writes an SSE comment (: keepalive) instead — the only line that is legal inside an unfinished event, at the price of being a line the client is free to ignore.
2. Auto-retry — transient gateway errors (401/403/429/5xx, e.g. "unauthorized client detected") are silently retried by the proxy with a linear backoff (RETRY_DELAY_MS, then twice that, and so on), so Claude Code never sees the error at all. When the gateway sends retry-after, that wins over our own schedule (capped at 30s, so a gateway can't park a request).
3. Pre-commit — ping injection only works once the gateway has sent response headers. If it hasn't within PRE_COMMIT_MS, the proxy sends the SSE headers itself and starts injecting pings; retries continue behind them. Streaming requests go upstream with accept-encoding: identity, because the proxy's own headers declare no compression and a gzipped upstream body would reach the client as garbage.
4. Hedging — after HEDGE_MS of silence the proxy fires a duplicate request in parallel and forwards whichever attempt answers first, aborting the rest. The winner's real status and headers are passed through, so nothing is faked.

Request headers are relayed verbatim (gateways fingerprint the client via user-agent, x-app, x-stainless-*, anthropic-version, anthropic-beta, authorization); only Host is rewritten to the upstream host, plus accept-encoding on streaming requests as described above. The token is never logged.

A note on hedging

Duplicates are billed and they add load. On a gateway that is short of upstream channels they make things worse, which is easy to measure: with HEDGE_MS=5000 and MAX_ATTEMPTS=5 against agentrouter the duplicate rate hit 2.4 per request and response times grew from 8s to 15–30s. Backing off to 20s / 2 attempts brought them back to 6–9s. The defaults are deliberately conservative — hedging here is a hang guard, not an accelerator.

Quick start

No npm dependencies, pure Node.js (built-in http/https/stream):

node proxy.js
node proxy.js selftest    # run the built-in checks and exit
node test-hedge.js        # hedging/pre-commit against a fake stalling gateway

On Windows you can also double-click proxy.bat (logs go to proxy.log).

Console panel

panel.bat opens a TUI against the running proxy: live counters, the remap target and the hedge knobs, all without a restart. It reads GET /__state, writes POST /__config, and starts the proxy itself (hidden) if the port is dead.

The knobs step through preset values rather than free arithmetic, so a slip can't set hedgeMs to something that floods the gateway.

PowerShell 5.1 needs panel.ps1 stored as UTF-8 with BOM, otherwise the box drawing and the arrows turn into mojibake. panel.ps1 -SelfTest checks the knob steps and the frame invariant (every row is exactly the frame width, so a long line can never wrap and make the frame scroll); -Once renders a single frame and exits. PANEL_COLS / PANEL_ROWS render at a size other than your window's.

Model remap

Claude Code calls claude-haiku-4-5-* for background tasks. If your token has no access to that model, the gateway answers 403 该令牌无权访问模型 and the session stalls. The proxy rewrites any model name containing HAIKU_MATCH to HAIKU_MODEL and fixes content-length. HAIKU_MODEL=off disables it.

The retry classifier also knows the permanent New API errors in Chinese (无权 / 过期 / 余额 / 额度 / 不存在 / 封禁 …) and does not waste attempts on them.

Point Claude Code at it

Edit ~/.claude/settings.json (Windows: C:\Users\<you>\.claude\settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
    "ANTHROPIC_AUTH_TOKEN": "sk-...",
    "ANTHROPIC_MODEL": "claude-opus-4-8"
  }
}

Change only ANTHROPIC_BASE_URL to http://127.0.0.1:8787; keep ANTHROPIC_AUTH_TOKEN and ANTHROPIC_MODEL as they were. Fully restart Claude Code.

The desktop Claude Code app reads the same settings.json, so the fix applies there too. The Claude Desktop chat app uses its own gateway setting in the UI — point it at http://127.0.0.1:8787 if you want to route it through the proxy.

Note that restarting the proxy kills the client's pooled keep-alive sockets, so the first request in every open window fails once with ECONNRESET ("check your network"). Press Esc and send again. That is why the settings that matter are runtime-patchable — see below.

Runtime config

Patched values are clamped to sane ranges and persisted to config.json, which takes precedence over the environment on the next start.

Both endpoints refuse any request that carries an Origin header. They mutate live config, and /__config parses a body of any content-type, which makes it a CORS "simple request" — without that check, any page open in your browser could POST to 127.0.0.1:8787 and flip your remap or set hedgeMs to a flood. The panel and curl send no Origin, so they are unaffected.

curl -X POST http://127.0.0.1:8787/__config \
  -H 'content-type: application/json' -d '{"hedgeMs":20000,"maxAttempts":2}'

Environment configuration

Example:

PORT=9000 UPSTREAM=https://other-gateway.example IDLE_MS=3000 node proxy.js

Reading the log

>> POST /v1/messages start                             request received
model remap claude-haiku-4-5-x -> claude-opus-5        remap applied
attempt #1 bounced 500: ...无可用渠道...               transient error, attempt dropped
hedge: 20016ms of silence, firing duplicate #2         silence, duplicate fired
duplicates aborted: 1                                  winner found, losers aborted
POST /v1/messages -> 200 (SSE) 21967ms                 upstream responded
pre-commit SSE (gateway silent for 10016ms)            headers sent by the proxy
POST /v1/messages ping #2                              event: ping injected
keepalive mid-event #3                                 comment: gateway stalled mid-event
stream closed normally: 12446b +2 keepalive in 13840ms   stream finished
CLIENT CLOSED the connection at 0b after 17833ms       client gave up before the first byte
GATEWAY TRUNCATED the stream at 4096b after 45000ms    upstream truncated the stream
all 2 attempts missed: ...                             every attempt failed, 502 to the client
client error: ECONNRESET                               connection-level failure

count_tokens -> 404 is normal — many gateways don't implement that endpoint.

The last three lines are the ones worth watching: they are the only cases where the client actually sees a failure.

License

MIT