Repository navigation
Releases
v0.7.0
Added
- Shared routes with configuration version 2. You can set access profiles for
your Claude and Codex subscription sign ins. You can also set named routes
with an ordered list of fallback targets. When one subscription reaches its
limit, the route uses the next target. A Claude route continues a
conversation with signed history after the proxy restarts. On a route, a
native Claude Messages response that is not streamed keeps its signed
thinking blocks, in the correct order, with complete usage. - Configs without
configVersion: 2keep the previous routing. - Access profiles accept only subscription sign ins. A profile or route that
names an API key account, an environment credential, API billing or
sameModelApifails at load. The error names the setting. - Access profiles and routes load only from your user config or from the file
thatSUBSWITCH_CONFIGnames. A project config file that sets them fails at
load. - The
subswitch models --schema-version 3 --client <client> --jsoncommand
shows the routes that a client can use. - The
subswitch run-actioncommand runs one native client command as one
routed action. Its tools and child agents use the same route. - Subswitch records upstream limit errors in a private local store by default.
Thesubswitch limits --jsoncommand shows them. Set
SUBSWITCH_LIMIT_DIRto change the store directory. Set
SUBSWITCH_LIMIT_RECORDING=0to turn the record off. - Register
gpt-6.2-sol,gpt-6.2-astra,gpt-6.1-terra, andclaude-fable-5-2in the built-in catalogs.
Explicitroutestargets accept these IDs with effortslow,medium,high,xhigh, andmax.
Model lists and doctor use these catalogs.
Native Codex discovery preserves OpenAI's own rows and adds Claude rows fromCLAUDE_MODELS. - Keep Terra 6.1 available by exact ID only through a preview entry.
Theterradefault stays ongpt-5.6-terra.
The Codex catalog requires Codex CLI 0.159.0 or later for Terra 6.1. - Apply Fable 5.2 limits on each translated path:
- The Codex-client reverse leg rejects disabled thinking and forced tool choice with 400.
It caps output at 128,000 tokens. - Claude Code explicit routes reject disabled thinking, forced tool choice, and
max_tokensabove 128,000 with 422target_capability_unavailable. - The default Anthropic passthrough applies no local limit.
- The Codex-client reverse leg rejects disabled thinking and forced tool choice with 400.
- Use the Codex effort set for Sol 6.2 and Astra 6.2.
Their model pages do not confirmxhighormaxper model.
These sets are not live-verified. - Subswitch sends
codex_cli_rs/0.144.6as its default user agent.
Access to the new Codex models with this value is not verified.
Setproviders.codex.userAgentto change this value.
Changed
- The
solandastrafamily aliases now resolve togpt-6.2-solandgpt-6.2-astra.
Older exact IDs remain routable. - The
fablealias on the Codex-client reverse leg now resolves toclaude-fable-5-2.
Older Fable exact IDs remain routable. - The lock file uses newer versions of
zod,wsand@clack/prompts.
v0.6.1
Fixed
- Configured Codex aliases now apply consistently to bare and provider-qualified
names, including overrides such assolandcodex:sol. - Future model IDs declared as alias targets can be requested directly, both as
the full ID and ascodex:<model-id>. Registered IDs and existing alias names
retain their precedence; unrelated unknown IDs remain unresolved. doctorreports unregistered configured targets as warnings without failing
the check solely for that reason. Unknown agent model names still fail.
Configured model IDs must be available to the upstream account. Forwarding an
override does not verify availability or add model capability metadata.
v0.6.0
Added
- GPT-6.1 Sol (
gpt-6.1-sol) with reasoning effortslow,medium,high,
xhigh, andmax. Unsupported efforts are dropped with a warning. - Claude Sonnet 5.5 (
claude-sonnet-5-5) and Haiku 5.5 (claude-haiku-5-5) on
the opt-in Codex → Claude leg, including native model discovery, 1M context
windows, and 128K output ceilings. Haiku defaults tomediumeffort; Sonnet
defaults tohigh.
Changed
solnow routes togpt-6.1-solwithout configuration.gpt-6-soland
older registered Sol IDs stay directly routable. Config overrides keep precedence.sonnetnow routes toclaude-sonnet-5-5;haikuroutes to
claude-haiku-5-5. Sonnet 5 remains directly routable. Sonnet 5.5 rejects
effortnoneand forced tool choice locally, matching its upstream restrictions;
Haiku 5.5 supports disabled thinking and forced tool choice.- Verified the remaining defaults: Astra 6, Luna 6, Terra 5.6, Opus 5.5, and
Fable 5.1. The README lists every family and its default target, and
subswitch models --client allexposes both effective catalogs. - Clarified that family aliases track the newest model registered in the installed
SubSwitch release. New provider releases require a SubSwitch update or a config
alias; the proxy does not discover or guess future versions at startup.
v0.5.0
Added
-
Astra routing:
gpt-6-astraand itsastrafamily alias, with Astra-specific
reasoning effort validation. -
Opt-in native Codex → Claude routing for Sonnet, Opus and Fable, while OpenAI
models continue to OpenAI and Codex retains native agents, tools and permissions. -
Subscription authentication, credential refresh, readable collaboration messages,
streamed/non-stream responses, prompt caching and bounded process-local replay. -
init,doctorandmodels --client codex|all, native model discovery, and a
user configuration fallback. Existing Claude Code setup remains the default. -
Live native acceptance runners and shared parity follow-ups in issues #45–#48.
-
--client allselects all supported clients;bothremains a compatibility alias. -
GPT-6 Sol and Luna:
gpt-6-solandgpt-6-lunajoin the forward registry. Both
accept reasoning effortlow,medium,high,xhighandmax;noneand
minimalare dropped with anunsupported_effort_droppedwarning. -
Claude Opus 5.5 (
claude-opus-5-5) on the Codex → Claude leg. -
Per-model Claude capabilities: each registered Claude model declares its output-token
ceiling, whether it always thinks, whether it accepts forced tool choice, and its default
reasoning level. Native Codex model discovery advertises that default per model (medium
for Opus 5.5,highfor the others). -
New reverse-leg 400 errors, returned before any upstream call:
reasoning_effort_unsupported_by_model(effortnoneon a model that always thinks:
Opus 5.5, Fable 5, Fable 5.1),tool_choice_unsupported_by_model(requiredor a named
tool on Opus 5.5 or Fable 5.1), andunregistered_claude_model(aclaude-*or
claude:*name that no registered model orcodexIngress.claude.aliasesentry routes).
Changed
-
Supported Node versions are
^22.15.0 || >=24, matching native zstd and runtime dependency requirements. -
Reverse routing includes the documented Claude identity preamble. Durable restart/compaction, setup undo and
explicit API authentication for translated inference remain separate shared work. -
User-level configuration now participates in every implicit config load, including
forward-only runs. Project fields override it; explicit config selection bypasses it.
Invalid user configuration can therefore prevent startup; diagnostics show its source. -
Raw relay headers named by
Connectionare stripped on both legs in both directions. -
Native Codex setup requires explicit trust for a custom upstream host before it writes files.
-
astrais now a reserved OpenAI model name for claude-ingress aliases (matched
case-insensitively, includingastra[...]family-suffix variants); a
codexIngress.claude.aliasesentry that claims it is rejected at config load,
and the relay refuses to start until the alias is removed or renamed. -
The
solandlunafamily aliases now resolve togpt-6-solandgpt-6-luna.
terrastays ongpt-5.6-terra.gpt-5.6-solandgpt-5.6-lunastill route by exact id
and appear as(direct)rows insubswitch models. -
The
opusalias on the Codex → Claude leg now resolves toclaude-opus-5-5.
claude-opus-5still routes by its exact id. -
gpt-5.5is retired ahead of its Codex shutdown on 2026-10-14. It still routes by exact
id (and ascodex:gpt-5.5), but it no longer wins a family alias, counts toward the
routable set (now 6 models) or appears in thesubswitch modelstable.
models --jsonlists it withretired: trueandroutable: false, anddoctorreports
an agent pinned to it as an info finding. -
fableandbestare reserved Claude Code model names alongsidesonnet,opus,
haiku,inheritandclaude-*, as the exact word or with a[...]suffix. They are
rejected asproviders.codex.aliaseskeys or targets, anddoctorno longer flags an
agent withmodel: fableas unresolvable. -
Reverse-leg
max_tokensis capped at the model's output-token ceiling.
Fixed
-
Unregistered
claude-*model names on the Codex → Claude leg are refused with
unregistered_claude_modelinstead of being forwarded to OpenAI, on HTTP, WebSocket
and over-window requests. -
doctorrecognisesClaude-*andclaude:*agent models as Claude names; its check was
previously case-sensitive and missed theclaude:form. -
The development HTTP recorder now captures eligible streamed
/responses
replies even when the upstream omitsContent-Type, without inspecting other
missing-header responses. -
Native Codex conversations can continue after cancelling a Claude response; pending
replay handles and ordered cancellation notices no longer cause 409/400 failures. -
Missing relay-side Claude credentials produce Claude-specific setup guidance without
triggering native Codex to refresh its unrelated OpenAI login. Lost continuation
errors now explain that a new conversation is required. -
Scope native credential substitution to exact Codex endpoints and redact synthesized
OpenAI errors at the JSON, SSE, and WebSocket render boundaries. -
Use async decompression, one shared continuation/replay budget, bounded upgraded
sockets, and the shared raw HTTP transport with one credential refresh retry. -
Classify translation, state, internal, and upstream failures explicitly; validate
malformed history/catalog values and bound recursive protocol traversal. -
Document all ingress configuration keys, model JSON schemas, and ingress log routes.
v0.4.0
Changed
limits.maxBodyBytesno longer applies to Anthropic-bound request bodies; renamed tolimits.maxBufferedBodyBytes. The relay buffers up to this many bytes to read themodelfield and route the request; a larger body is now streamed toapi.anthropic.comverbatim instead of being answered with a relay-synthesized413 request_too_large, because Anthropic enforces its own payload limits with authoritative errors and a proxy-invented 413 misattributes proxy policy as upstream state (ADR-010). A body above the window whose leadingmodelresolves to a translated provider (Codex) still returns413 request_too_large— on that leg subswitch is the origin and cannot translate a body it cannot hold.- BREAKING: a config containing
limits.maxBodyBytesrefuses to start with a message naming the replacement key. Peak memory for Anthropic-bound requests with a declared-over-window Content-Length drops from ~2× the body to a bounded ~8 KiB prefix plus stream backpressure; for chunked or undeclared over-window bodies, the relay still buffers up to one routing window plus one socket read before the trip fires.
v0.3.0
Fixed
-
Codex auth concurrent-refresh guard — replaced the lexicographic string
>comparison
onlast_refreshtimestamps inpersistTokenswith a refresh-token identity check
(fileNow.tokens.refresh_token !== refreshToken). The old comparison depended on the
Codex CLI emitting byte-identical ISO-8601 formatting indefinitely; a format divergence
or same-second collision could cause the guard to miss, letting subswitch clobber the
CLI's rotated refresh token. The identity check is format-independent and is the
established idiom already used in theinvalid_grantretry path. ADate.parsenumeric
comparison is kept as a secondary signal for correct ordering when timestamp formats
differ (e.g."…08:00:05.500Z"vs"…08:00:05Z"sorts wrong lexicographically but
right numerically). (Fixes #26) -
Codex auth guard bypass on materialFrom failure — when
fileIsNeweris true but
materialFromfails on the newer file, the branch now serves the just-refreshed tokens
from memory rather than returning an error. The newer file's refresh_token is still never
clobbered (no write occurs); the request succeeds using the valid tokens we hold.
Previously, control fell through into the merge and wrote our refresh result anyway,
defeating the guard even when it had correctly fired. -
Anthropic passthrough —
connectTimeoutMsnow genuinely bounds DNS resolution and
TCP establishment (fixes #27).
Previouslyupstream.setTimeout(connectTimeoutMs)was called on theClientRequest
object, but Node's implementation defers that call via an internal'connect'
listener — so it fired only after TCP connect, meaningconnectTimeoutMswas never in
force for any measurable interval. Measured against a blackholed IP (192.0.2.1,
TEST-NET-1) withconnectTimeoutMs=700, the request previously failed after
75 019 ms (the macOS kernel TCP timeout). The fix arms the timer directly on the
socket inside the'socket'event handler, before DNS resolves, so the budget covers
the full connect window: DNS lookup plus TCP SYN/ACK. The same measured scenario now
fails at ~700 ms. Upgrade note: operators with a slow DNS resolver may now see
connectTimeoutMs504s that 0.2.0 would have passed through — the budget is now
enforced for the first time. -
Anthropic passthrough —
x-subswitch-synthesized: 1header marks every relay-generated response; stripped from proxied responses (stacks on #30).
Previously a relay fault (502 connection failure, 504 timeout, 500 internal proxy error, 413 body too large,
431 header fields too large) was indistinguishable from an upstream outage on the client side. Every response the
relay synthesises itself now carriesx-subswitch-synthesized: 1; this covers the Anthropic-leg error
paths, all codex-leg responses (both streaming SSE and aggregated JSON — the codex leg translates
Codex→Anthropic format so every byte it returns is relay-synthesised), and every relay-generated error in
server.ts. On the proxied path the header is actively stripped from upstream responses via the hop-by-hop
filter so an origin that sets it cannot impersonate the relay. Bodies and status codes are unchanged — the
header is purely additive. See the new## x-subswitch-synthesizedsection in the README for the
operator-facing wire contract. -
Anthropic passthrough — a pre-header upstream timeout no longer produces a spurious
anthropic_upstream_errorwarn (fixes #27). In 0.2.0, when the Anthropic upstream
timed out before sending response headers, the relay emitted two simultaneous warn
events —anthropic_upstream_timeoutandanthropic_upstream_error— because
destroying the timed-out request caused a second error event that the error handler
logged unconditionally. In 0.3.0, at most one warn event fires per upstream request:
whichever terminal outcome responds first claims the log slot; any subsequent error
event is silently discarded. -
404 responses now use the same Anthropic-shaped error body as all other synthesized
errors. Previously an unknown path returned a bare 404 with no body. The body now
carries{ type: "error", error: { type: "not_found_error", message: "…" } }and the
x-subswitch-synthesized: 1marker, matching every other relay-generated response. -
Unhandled-exception route labeled
internal_errorin therequest_completelog.
When an unexpected exception occurs during request handling, theroutefield in the
request_completeevent is now"internal_error"rather than whatever routing label
was in effect when the exception fired. This makes relay-side panics distinguishable
from normal traffic in post-hoc log analysis.
Changed
-
anthropic.maxUpstreamSocketsdefault raised from 32 to 256. With no relay-side
concurrency cap, the old pool of 32 sockets created silenthttp.Agentqueuing at
realistic peak load (~100 concurrent Claude Code sub-agents). 256 gives comfortable
headroom over realistic peak concurrency. -
Colon-bearing model names with unknown prefixes now forward to Anthropic instead of
returning a relay-invented 400. When a model name likeclaude-sonnet-9:preview
contains a colon whose prefix is not a registered provider, the relay logs a diagnostic
warning and forwards to Anthropic unchanged. Realcodex:qualified names continue to
route to the Codex provider as before. -
Ambiguous model family names now forward to Anthropic instead of returning a
relay-invented error. When two providers claim the same family name, the relay logs an
ambiguous_model_namewarn carrying the provider list and forwards the request to
Anthropic unchanged (ADR-010: the relay has no authority to adjudicate a registry
conflict it did not cause). -
doctorunknown_providerfinding downgraded fromfailtoinfo. An agent
frontmatter naming a colon-qualified model with an unknown prefix (e.g.myco:mymodel)
previously produced a severityfailfinding and causedsubswitch doctorto exit 1.
Because the relay now forwards those requests to Anthropic unchanged, the finding is
informational — the agent works, just not via Codex.ambiguous(two providers claim
the same family name) remainsfail: that conflict is relay-derived and will 404 at the
origin regardless of which upstream handles it. -
413 now uses error type
request_too_largeinstead ofinvalid_request_error,
matching the Anthropic API's own error taxonomy for oversized bodies. A 413 response
now also drains the remaining upload bytes before closing the connection, with a 2-second
hard cutoff; in 0.2.0 the connection closed immediately, which could prevent the client
from reading the 413 body if its TCP write buffer was still filling. -
SERVER_TUNINGconstants set explicitly on the HTTP server:requestTimeout
(600 s — Anthropic's own server-side ceiling for long-running requests),headersTimeout
(120 s — maximum time to receive all request headers),keepAliveTimeout(300 s —
matches Anthropic's idle-socket keepalive window so the relay's pool never evicts a
socket the origin still considers live),maxRequestsPerSocket(unlimited, matching
the Anthropic origin's behaviour), andmaxHeaderSize: 64 * 1024(raises the inbound
header ceiling from Node's 16 KiB default to 64 KiB — also determines when the relay
fires a 431 Header Fields Too Large). Previously these values were whatever Node's
built-in defaults happened to be. Inbound timeouts (requestTimeout,
headersTimeout) that expire now return an Anthropic-shaped408with
x-subswitch-synthesized: 1; in 0.2.0 Node emitted its own unshapeable bare408
that no relay code produced or logged.
Added
request_too_largeandnot_found_erroradded to the internalAnthropicErrorTypeunion.client_disconnectedlog event — emitted (atinfolevel) when the client closes the
connection before any response headers are sent (e.g. a cancelled upload). Fields:path,
route,model(optional),latencyMs.request_completeis not emitted for the same
request — the two events are mutually exclusive. This distinguishes an abandoned request from a
served one: without this event, a vanished client would either produce no log entry or a
misleadingrequest_complete status=200(Node's default initialiser, not a real status).- Two new
routevalues for fail-open forwards —anthropic:ambiguous(two providers claim
the same family name) andanthropic:fallback(colon-qualified name with an unknown prefix).
Both carry theanthropicprefix so leg-level filtering continues to work; the suffix makes
fail-open forwards distinguishable from intended Anthropic routes inrequest_completeand
client_disconnectedlog queries.
Changed
routefield: three values retired on this branch. Operators filtering logs onroute
should update their queries:"rate_limited"— removed with the admission gate; requests are no longer rejected at the
relay level for rate-limit reasons."ambiguous"— replaced by"anthropic:ambiguous"(fail-open forward; see above)."unknown_provider"— replaced by"anthropic:fallback"(fail-open forward; see above).
Removed (BREAKING)
-
Two config keys are now fully removed and produce a hard error on load if present.
Delete these keys from yoursubswitch.config.jsonbefore upgrading:anthropic.streamIdleTimeoutMs— the relay does not bound the stream-idle phase on a
connected client (ADR-010).limits.maxConcurrentRequests— the admission gate was removed (ADR-010).
If your config contains either of these,
subswitchexits immediately with a message
naming every offending key.
v0.2.0
[0.2.0] - 2026-08-09
Upgrading from 0.1.0
A 0.1.0 subswitch.config.json will not start the server. If you copied the
example config shipped with 0.1.0, or wrote a config in the old layout, the process
exits immediately with:
outdated config layout in subswitch.config.json — move `codex` to `providers.codex`; move `reasoningCache` to `providers.codex.reasoningCache`; move `limits.connectTimeoutMs` to `anthropic.connectTimeoutMs`; move `limits.maxUpstreamSockets` to `anthropic.maxUpstreamSockets`; move `limits.streamIdleTimeoutMs` to `anthropic.streamIdleTimeoutMs and/or providers.codex.streamIdleTimeoutMs`; move `limits.requestTimeoutMs` to `providers.codex.requestTimeoutMs`; move `limits.maxSseEventBytes` to `providers.codex.maxSseEventBytes`; move `codex.models` to `(removed — routing now follows the built-in model registry; use providers.codex.aliases for custom names)`. Edit the file to match subswitch.config.example.json, or delete it to run on defaults.
Two ways forward:
- Edit
subswitch.config.jsonto match the newsubswitch.config.example.jsonlayout
(the migration table in the Breaking Changes section below lists every key that moved). - Delete
subswitch.config.jsonand run on defaults — the proxy works out of the box
once Codex auth is in place.
Warning — migrating the
codexblock wholesale: The migration table's first row
sayscodex.*moves toproviders.codex.*. Copying the entire oldcodexblock
as-is carries the removedcodex.modelskey along with it. The schema uses strict
key checking, soproviders.codex.modelsproduces a second, less helpful error rather
than the guided migration message above. Dropmodelsfrom the block before copying.
Breaking Changes
Non-default base URL hosts now refused by default
subswitch serve now exits with an error if providers.codex.baseUrl,
providers.codex.oauthTokenUrl, or anthropic.baseUrl points at a host other than
the provider's expected default (chatgpt.com, auth.openai.com, and
api.anthropic.com respectively), unless the new opt-in key is set.
Previously, a non-default host emitted a startup warning and the server started
anyway. A warning is easy to miss in a long serve session, and a hostile
subswitch.config.json in a cloned repository would silently forward the user's
subscription credentials and OAuth refresh token to an attacker-chosen host.
If you were intentionally overriding a URL to route through a trusted proxy, add
the opt-in key to your subswitch.config.json:
{
"providers": {
"codex": {
"baseUrl": "https://your-proxy.example.com/...",
"oauthTokenUrl": "https://your-proxy.example.com/...",
"allowInsecureBaseUrl": true
}
}
}Or for the Anthropic leg:
{
"anthropic": {
"baseUrl": "https://your-proxy.example.com/v1",
"allowInsecureBaseUrl": true
}
}Loopback addresses (127.*, localhost, ::1) are always exempt — the e2e
wire-recorder workflow (http://127.0.0.1:4142) continues to work without the opt-in.
oauthTokenUrl is also gated because it carries the long-lived OAuth refresh token —
more damaging to expose than the short-lived access token in baseUrl.
Config file format restructured
This is a breaking change if you have an existing subswitch.config.json. There
is no automatic migration and no compatibility shim. A compatibility shim was not
written because Zod's default behaviour strips unknown keys — a shim would have
silently reverted any custom settings the old keys held to their defaults rather than
carrying them forward, which is worse than a hard error. The change is enforced loudly
at load instead.
What moved and what was removed:
| Old key | New location |
|---|---|
codex.* (entire block) |
providers.codex.* |
reasoningCache.* (top-level) |
providers.codex.reasoningCache.* |
limits.connectTimeoutMs |
anthropic.connectTimeoutMs |
limits.maxUpstreamSockets |
anthropic.maxUpstreamSockets |
limits.streamIdleTimeoutMs |
anthropic.streamIdleTimeoutMs and/or providers.codex.streamIdleTimeoutMs |
limits.requestTimeoutMs |
providers.codex.requestTimeoutMs |
limits.maxSseEventBytes |
providers.codex.maxSseEventBytes |
codex.models |
Removed — routing now follows the built-in model registry; use providers.codex.aliases for custom names |
Two subswitch init flags were also removed:
| Old flag | Replacement |
|---|---|
--codex-model <name> |
Removed — use providers.codex.aliases in config to map custom model names |
--codex-models <csv> |
Removed — use providers.codex.aliases in config to map custom model names |
An old config file is rejected at load with an error that names each key and its
replacement. This is intentional: Zod's default behaviour strips unknown keys, so
without the detection gate every custom setting would silently revert to defaults.
For the same reason, a providers.<id> block written under an id subswitch does not
ship — a typo like providers.codexx, or a provider from a future release — is also
rejected at load, naming the offending key and listing the known provider ids.
Such a block would otherwise be stripped by the schema and do nothing at all.
Added
providers.codex.allowInsecureBaseUrl(defaultfalse): opt-in that permits
providers.codex.baseUrlorproviders.codex.oauthTokenUrlto point at a
non-default host. When the gate fires, the error message names the offending host,
the config key, and this opt-in key.anthropic.allowInsecureBaseUrl(defaultfalse): same gate for the Anthropic
passthrough leg.providers.codex.maxAggregateBytes(default67108864, 64 MiB): maximum total
byte budget for a non-streaming Codex response. Responses that exceed this limit are
rejected with a 502 rather than accumulating unbounded memory.codex_base_url_host_rejectedlog event (error level): emitted when the
host-rejection gate fires for a Codex URL. Event name is a compile-time template
literal over theProviderIdunion — part of the log-injection barrier.anthropic_base_url_host_rejectedlog event (error level): emitted when the
gate fires for the Anthropic leg.- Model family aliases:
sol,terra, andlunaare now validmodel:values
in agent frontmatter. Each alias resolves to the highest-generation canonical id
for that family (e.g.sol→gpt-5.6-sol). Resolution follows five rules in
priority order: exact registry id, custom alias override, qualifiedprovider:name,
family (unique claimant), then unresolved (passes to Anthropic). subswitch models: new subcommand that prints the effective model registry and
alias resolution table under the current config.--jsonemits a machine-readable
document (see README §subswitch models --json) with an integerschemaVersion
contract.genis an integer tuple ([5, 6]) rather than a string ("5.6")
because string comparison sorts"5.10"before"5.9".previewandretired
are always-present booleans. Anthropic is listed with zero model rows — we
prefix-match Claude names and cannot enumerate them; fabricating a list would be a
lie consumers cache.providers.codex.aliasesconfig key: free-form map of custom model name
overrides. Aliases win over derived family aliases but never over exact registry ids.
Neither key nor target may be an Anthropic model name; such a config is rejected at
load because either side would route main-agent traffic to Codex.subswitch doctorper-provider diagnostics: doctor fans out to all configured
providers, prints a per-provider ready banner on startup, and scans.claude/agents/
and~/.claude/agents/for six finding kinds:unresolvable,ambiguous,
unknown_provider,retired,provider_unconfigured, andpreview_only.
Anthropic-named subagents are skipped. Finding severity follows provider configuration
— a provider the user never configured stays informational; only explicitly configured
providers can fail the exit code.limits.maxConcurrentRequests(default:32): in-flight request ceiling. Requests
above this limit receive an immediate 503. Protects against burst overload and makes
resource usage predictable.providers.codex.requestTimeoutMs,providers.codex.streamIdleTimeoutMs,
providers.codex.maxSseEventBytes: three per-Codex-leg timeout/size limits,
split out from the old flatlimits.*block.writeFrameabort safety: the SSE frame drain wait is now raced against the
request abort signal, preventing a hang when the client disconnects mid-stream./healthendpointproviders[]: the health JSON now includes aproviders
array so monitoring scripts can check provider-level ready state without parsing
server logs.- New modules:
anthropic-wire-types.ts,anthropic-parse.ts,
provider-transport.ts,provider-handler.ts,provider-auth.ts,
provider-events.ts,models.ts,agent-scan.ts— provider-neutral seams,
the pure model registry, and the agent frontmatter scanner.
Changed / Behavior
codex.modelsdeleted: the user-maintained model allowlist is gone. The compiled-in
MODEL_REGISTRYis now the sole source of the routable set, built into a
RoutingTableonce at startup bybuildRoutingTable. This is not a capability loss:
every Codex route traces back to a model name the user wrote in agent frontmatter,
and Codex auth is already a second gate. Aproviders.codex.aliasesentry (rule 2)
shadows a derived family alias but can never shadow an exact registry id (rule 1).subswitch initno longer asks about model selection and no longer writes a
codex.modelskey to config. The routing decision belongs to the agent frontmatter.- **`decideRo...
v0.1.0
Added
- Proxy core: local subscription-routing proxy that splits Claude Code traffic
by model name — requests whosemodelmatches thecodex.modelslist are
translated and forwarded to the Codex backend; everything else is relayed to
Anthropic verbatim. subswitch serve: starts the proxy on127.0.0.1:4141(configurable with
--port); accepts--verbose/--quietlog-level overrides for the session.subswitch doctor: preflight health check that reports config, codex auth
status, subswitch-running probe, and TLS reachability for both upstream hosts.subswitch init: interactive wizard (powered by@clack/prompts) that
writessubswitch.config.jsonand wiresANTHROPIC_BASE_URLinto the Claude
Code settings file; supports--yesfor non-interactive execution and--dry-run
to preview the planned writes without touching the filesystem.- Codex leg: full Anthropic Messages → OpenAI Responses translation including
system prompts, tool calling, reasoning round-trip cache (bounded LRU), and
effort-control forwarding (output_config.effort→reasoning.effort). - Codex OAuth: reads
~/.codex/auth.json, proactively refreshes access
tokens, and retries once on a 401. subswitch.config.json: optional project-level config for port, log level,
model list, reasoning cache limits, and upstream socket pool size.
Changed / Behavior
doctorexits non-zero when any check fails — exit code 0 means all
checks passed; exit code 1 means at least one check failed. This makes
subswitch doctorusable as a preflight gate in scripts and CI pipelines.
(Note: do not invokedoctorbare underset -ein CI — in CI environments
the live checks will always fail because the proxy is not running and codex
auth is not configured. Usesubswitch --versionfor a "binary resolves"
smoke check instead.)- Strict per-command flag rejection — a known flag passed to the wrong
command (e.g.doctor --verbose) now produces a clean error and exits 1
instead of being silently accepted or ignored. initfails closed on non-TTY / CI — runningsubswitch initwithout
--yesin a non-interactive environment (no TTY, orCIenv var set) exits 1
immediately and writes no files. Use--yesto opt in to non-interactive mode
with explicit intent.--dry-runis the only exception — it works in all
contexts because it writes nothing.- Misapplied and unknown flags produce clean
subswitch:-prefixed errors —
no stack traces; exit code 1 with a human-readable message and a pointer to
--help.