ghuntley / underclass

# underclass
**A local proxy that pools multiple ChatGPT/Codex, GitHub Copilot, and Claude Code subscriptions behind one endpoint.**
 [code] 
One subscription runs out of quota? It leaves rotation until its window resets — and comes back on its own. Sessions stay pinned to one subscription so upstream prompt caches stay warm. When *everything* is exhausted, the proxy fails fast with the earliest reset time instead of hanging.
---
## Why
Subscription-based model access has a per-account quota. One account is a ceiling; twenty accounts are a pool. underclass turns a pile of personal subscriptions into a single durable endpoint that behaves like one well-provisioned provider:
- **No client changes** — the surface is plain `/v1/*`; point opencode (or anything OpenAI-compatible) at it.
- **No quota whiplash** — exhausted accounts cool down and recover automatically; clients never see account churn.
- **No cache waste** — sessions are sticky, so the upstream prompt cache keeps working across turns.
## Quick start
 [code] 
 [code] 
Keep the generated values in a password manager or runtime secret file; underclass
never writes them to diagnostics. Open the web UI and paste the value supplied as
`UNDERCLASS_UI_TOKEN`.
1. Open the web UI and paste the configured admin token.
2. Click **Add account** → pick *ChatGPT / Codex*, *GitHub Copilot*, or *Claude Code (Anthropic)* → follow the flow. The account is labeled automatically with the account's email or username.
3. Repeat for every subscription you want in the pool.
4. Point opencode at the pool:
 [code] 
`underclass connect` writes the provider block and credentials into your global opencode config (`~/.config/opencode/opencode.json{,c}` + `auth.json`), idempotently and with backups. Re-run it any time; `--remove` undoes it.
5. Point Claude Code at the same pool (it speaks the Anthropic surface):
 [code] 
`CLAUDE_CODE_OAUTH_TOKEN` is what the official client uses when an auth-injecting proxy sits in front of it: the client keeps its Claude Code request shape and sends the proxy key as its bearer token, and underclass replaces that with the pooled subscription credential.
## How routing works
- **Sticky sessions.** Requests carrying `prompt_cache_key` / `promptCacheKey` (opencode sends the session ID when configured with `setCacheKey: true`) always land on the same subscription. Bindings live for 24h, survive restarts, and rebind preferentially within the same backend when an account cools.
- **Health pool.** A quota response moves an account to *cooling* until the upstream deadline or a per-backend default. Codex uses the later valid deadline from its usage-limit error and `retry-after`, and its account usage poll can extend cooldown to a later exhausted-window reset or readmit an account when upstream reports it allowed. 401s trigger one token refresh + retry, then the account needs re-login. Cooling accounts stay configured and return to rotation automatically.
- **Codex usage and banked resets.** The