# AI use cases for Underclass (ghuntley/underclass)

Repo: [ghuntley/underclass](https://github.com/ghuntley/underclass) | Use cases: 4 | Page: https://dedupedai.com/use-cases/ghuntley-underclass/

underclass is a local Rust proxy that pools multiple ChatGPT/Codex, GitHub Copilot, and Claude Code subscriptions behind one OpenAI-compatible and Anthropic-compatible endpoint.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Point opencode at a pool of coding subscriptions: https://dedupedai.com/use-cases/ghuntley-underclass/pool-subscriptions-for-opencode/
- Route Claude Code through a pool of Claude subscriptions: https://dedupedai.com/use-cases/ghuntley-underclass/route-claude-code-through-subscription-pool/
- Watch pool quota, cooldowns, and plans in real time: https://dedupedai.com/use-cases/ghuntley-underclass/watch-pool-quota-and-cooldowns-live/
- Audit token use and stream failures over the last week: https://dedupedai.com/use-cases/ghuntley-underclass/audit-token-use-and-stream-failures/

## How to point opencode at a pool of coding subscriptions with Underclass

Repo: [ghuntley/underclass](https://github.com/ghuntley/underclass) | Difficulty: Intermediate | Time: 45 minutes | Basis: From the README

Run one local endpoint that spreads opencode requests across several Codex or Copilot accounts.

**Who it is for:** A developer who uses opencode daily and has more than one ChatGPT/Codex or Copilot subscription, and hits quota limits on a single account.

**The problem:** Each subscription has its own quota, so one account running out interrupts coding sessions and forces manual switching between logins.

**The outcome:** opencode talks to one local URL, sessions stay pinned to one account, and exhausted accounts leave rotation until their window resets.

### Steps

1. Clone the repo and, from its root, run `UNDERCLASS_PROXY_KEY="$(openssl rand -hex 32)" UNDERCLASS_UI_TOKEN="$(openssl rand -hex 32)" cargo run -- serve` and keep the generated values in a password manager. (inferred, check the README)
2. Open http://127.0.0.1:8080/ in a browser, paste the value you set as UNDERCLASS_UI_TOKEN, click Add account, and sign in to each ChatGPT/Codex or Copilot subscription you want in the pool.
3. In a second terminal, run `cargo run -- connect` to write the provider block into your global opencode config.
4. Run `opencode --provider underclass --model underclass/gpt-5.5` and send a prompt.
5. Check the admin page to confirm the request was attributed to one account and that its prompt cache key appears in the usage rows.

### Prompt to paste into your agent

```text
In the underclass repo at <repo path>, start the server with the proxy key and UI token set as environment variables, run `cargo run -- connect`, then run one opencode prompt against the underclass provider. Expected output: a completed response and a usage row in the admin page for <account label>. Verify that the admin page lists the account as healthy after the request.
```

### Caveat

The README says state lives in ~/.local/share/underclass/pool.db and that deleting it starts fresh, so losing that file means re-adding every account.

Risk, account pooling: Pooling several personal subscriptions behind one endpoint may conflict with the terms of the providers that issued them, so check those terms first.

Risk, credentials: The proxy stores provider credentials in a local SQLite database, so protect the database and the minted keys.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/ghuntley-underclass/pool-subscriptions-for-opencode/

## How to route Claude Code through a pool of Claude subscriptions with Underclass

Repo: [ghuntley/underclass](https://github.com/ghuntley/underclass) | Difficulty: Intermediate | Time: 45 minutes | Basis: From the README

Point the official Claude Code client at a local proxy that rotates across several Claude Code accounts.

**Who it is for:** A developer who runs Claude Code heavily and owns more than one Claude Code subscription, and wants work to continue when one account's windows are used up.

**The problem:** Anthropic subscription quota is window-based, so a single account can stop mid-task when its session or weekly window runs out.

**The outcome:** Claude Code keeps its normal request shape and reaches the Anthropic surface through Underclass, which swaps in a pooled credential and cools exhausted accounts until their window resets.

### Steps

1. Start the server with `cargo run -- serve` after setting UNDERCLASS_PROXY_KEY and UNDERCLASS_UI_TOKEN as in the README quick start.
2. Open the web UI, click Add account, choose Claude Code (Anthropic), and complete the OAuth paste-back flow for each subscription.
3. Export the base URL with `export ANTHROPIC_BASE_URL=http://127.0.0.1:8080`.
4. Set CLAUDE_CODE_OAUTH_TOKEN to the value of your UNDERCLASS_PROXY_KEY, since the README says the client sends the proxy key as its bearer token.
5. Start Claude Code in the same shell and run a short task, then check the admin page for the plan and the three quota windows of the account used.

### Prompt to paste into your agent

```text
In the underclass repo at <repo path>, start the server, export ANTHROPIC_BASE_URL and CLAUDE_CODE_OAUTH_TOKEN as the README describes, and run one short Claude Code task. Expected output: a completed task and a request row for a Claude Code account in the admin page. Verify that the account's plan and its 5-hour, 7-day, and model-scoped windows are shown.
```

### Caveat

The README says the Anthropic surface only serves the official Claude Code client and requires its headers and identity block, so other Anthropic clients will be rejected.

Risk, account pooling: Using several personal Claude Code subscriptions through one proxy may fall outside Anthropic's terms, so confirm that use is allowed for your accounts.

Risk, credentials: The proxy key you place in CLAUDE_CODE_OAUTH_TOKEN grants access to the whole pool, so do not paste it into shared logs or tickets.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/ghuntley-underclass/route-claude-code-through-subscription-pool/

## How to watch pool quota, cooldowns, and plans in real time with Underclass

Repo: [ghuntley/underclass](https://github.com/ghuntley/underclass) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Open a live terminal monitor that shows in-flight requests, account states, and quota windows.

**Who it is for:** A developer or operator running Underclass for a team of personal subscriptions who needs to know which accounts are cooling and when they return.

**The problem:** When accounts cool down silently, it is unclear why requests are slowing or failing and when capacity comes back.

**The outcome:** A read-only dashboard shows which accounts are healthy, which are cooling and until when, and which plan each account uses.

### Steps

1. Run `cargo run -- serve` in one terminal and keep it running.
2. In a second terminal, run `underclass top` (or `utop` from the Nix package).
3. Read the PLAN column and the account status column, and note the cooldown deadlines shown for any cooling account.
4. Press j or k to scroll the account list, and press q to quit when finished.

### Prompt to paste into your agent

```text
In the underclass repo at <repo path>, with the server running, start `underclass top` and capture the account table. Expected output: one row per configured account with a status label and plan. Verify that each cooling account shows a reset time and that the PLAN column is filled or marked unknown.
```

### Caveat

The README says top reads the monitor snapshot, which includes account labels and usage, so keep that terminal session away from shared screens.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/ghuntley-underclass/watch-pool-quota-and-cooldowns-live/

## How to audit token use and stream failures over the last week with Underclass

Repo: [ghuntley/underclass](https://github.com/ghuntley/underclass) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Summarize requests, tokens, and failed streams per model or account from the local database.

**Who it is for:** A developer or team lead who wants to know which models and accounts used the pool and where streams failed.

**The problem:** Without a record, it is hard to tell whether failures came from capacity, policy errors, quota, or upstream stream breaks.

**The outcome:** A table of requests, tokens in and out, concurrency, failed streams, and events for the chosen window, plus a dry run of any Codex rollout backfill.

### Steps

1. With the server running, run `underclass stats --since 7d --by model` to see totals per model. (inferred, check the README)
2. Run `underclass stats --since 7d --by account` to compare accounts. (inferred, check the README)
3. Read the failed streams and the overloaded, policy, quota, cooling, and saturated event columns.
4. Run `underclass stats import-codex --dry-run` to preview any capacity or policy errors that can be backfilled from Codex rollout logs. (inferred, check the README)
5. Run `underclass stats --since 7d --by model --json` if you need the output in a script. (inferred, check the README)

### Prompt to paste into your agent

```text
In the underclass repo at <repo path>, with the server running, run `underclass stats --since 7d --by model` and save the output. Expected output: a UTC table with requests, tokens in and out, and event columns. Verify that the totals match the sum of the per-model rows.
```

### Caveat

The README says historical rows remain queryable after account removal, but statistics are kept only for the retention set in stats_retention_days, which defaults to 730 days.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/ghuntley-underclass/audit-token-use-and-stream-failures/