tokenmaxxing 1.64.0 → 1.66.0

package/DESIGN.md

@@ -31,19 +31,19 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
 - Five `~/.claude/settings.json` entries (merged - other settings keys are preserved, but the `statusLine` slot is taken over): the tokenmaxxing `statusLine` renderer (native since 2026-07-11; it also tees usage), a `subagentStatusLine` (per-subagent rows in the agents panel), a `Stop` hook, a `StopFailure` hook, a `SessionStart` hook.
 - **`~/.config/tokenmaxxing/`** - the single home for config and state:
   - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin/grokBin/opencodeBin pins, policy.*); defaults apply at read time, `xx config` prints the path and the effective values, and edits happen in an editor.
-  - `accounts.json` - non-secret index `{id, label, email, tier, addedAt, windows, lastUsageAt, lastProbeAt, probeFails, storeFails, enforcedUntil, needsReauth, oauthAccount}` (each cached window carries its name, duration, reset, and sample time; the same shape serves the Codex pool as `codex-accounts.json`). Neither index names an active account: the schema is `{version, accounts}`, and an older file that still carries `activeId` loads and drops the key on the next save.
+  - `accounts.json` - non-secret index `{id, label, email, tier, addedAt, windows, lastUsageAt, lastProbeAt, probeFails, storeFails, usageRetryAt, enforcedUntil, needsReauth, oauthAccount}` (each cached window carries its name, duration, reset, and sample time; the same shape serves the Codex pool as `codex-accounts.json`). Neither index names an active account: the schema is `{version, accounts}`, and an older file that still carries `activeId` loads and drops the key on the next save.
   - `stores/<uuid8>/` - one Claude Code credential store per pooled account (see below).
   - `codex-stores/<uuid8>/` - one Codex credential store per pooled account: its `auth.json`, with everything else symlinked to the shared `~/.codex` so sessions, history, and config stay shared and `codex resume` works across stores.
   - `usage/<uuid8>.json` - the statusline tee per account, written by the sessions running on it.
   - `live/<session-id>` - PID-validated presence per supervised session, naming its account; placement counts them.
   - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal): the target account, the session to resume, a `waitUntil`, a `compact` flag, and the launch time the marker was written for.
   - `bin/claude` and `bin/codex` - the supervisors, beside the `tokenmaxxing` and `xx` entry points.
-  - `sessions/<sid>.json`, `onboard/`, `setup-tokens.json`, `setup-token/`, `cloud/`, `update.json`, `spawnrate.json`, `tokenmaxxing.log`, the codex `codex-onboard/`, `codex-respawn/`, and `codex-live/`, and the `grok-*` and `opencode-go-*` state of the status-only pools: the full table is in [State directory layout](docs/content/docs/state-directory.mdx).
+  - `sessions/<sid>.json`, `onboard/`, `setup-tokens.json`, `setup-token/`, `cloud/`, `hub-key`, `update.json`, `spawnrate.json`, `tokenmaxxing.log`, the codex `codex-onboard/`, `codex-respawn/`, and `codex-live/`, and the `grok-*` and `opencode-go-*` state of the status-only pools: the full table is in [State directory layout](docs/content/docs/state-directory.mdx).
 - Per-account **credential stores** follow the platform's Claude Code store: macOS = a login-keychain item keyed by the store path (never plaintext on disk); Linux = a 0600 `.credentials.json` inside the 0700 store directory (the same plaintext model claude itself uses - its Linux build has no keyring path at all, binary-verified 2.1.205). One `credstore` facade dispatches on a `{kind: keychain|file}` target; call sites never branch on platform. tokenmaxxing writes a store once, at onboarding; Claude Code's own refresh is the only writer afterwards.
 
 - A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check` once per tick (`policy.checkIntervalMs`, 60s by default): it runs the decision with no seat (nothing moves), folds fresh tees into the index, samples up to three accounts whose last sample attempt is oldest (the direct no-spend usage GET), deletes leftover dead state files at the state root, and on a Bun global install checks npm for a newer version once a day, so the cached figures every placement reads stay fresh.
 
-The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. The `claude` binary, `~/.claude.json`, and Claude Code's default credential store are untouched; inside `~/.claude` only `settings.json` gets the five entries.
+The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. `tokenmaxxing serve`, the optional [usage hub](docs/content/docs/hub.mdx) that answers the CLIProxyAPI management subset for a dashboard from the cached figures, is a foreground server outside the switching path. The `claude` binary, `~/.claude.json`, and Claude Code's default credential store are untouched; inside `~/.claude` only `settings.json` gets the five entries.
 
 ---
 
@@ -84,7 +84,7 @@ Each terminal ran the supervisor, so each has its own child `claude`, its own `-
 The [switching policy](docs/content/docs/switching.mdx) is one rule: under both bars, hold; at or over a bar, move to the usable account that ranks first; nothing usable, wait for the soonest reset. The same ranking places a session at launch.
 
 - Ranking (decided by consult for #79): greatest remaining headroom to the session bar divided by the number of sessions after placement, `(bar - used) / (sessions + 1)`, then highest pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, over time to its reset), then soonest weekly reset, then lowest weekly usage; unknown usage ranks last. Organization membership is not an input. Codex drops the headroom key, keeps the pace ordering and the weekly tie-breaks, and excludes accounts running in another codex session, because codex has no cross-process refresh lock and two sessions must never share a login.
-- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, over the direct no-spend usage read with the account's stored token, so every account is attempted about once per three ticks per pooled account, or once per `policy.usagePollTtlMs` plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. An expired stored access token stays unmeasured until a session on that store refreshes it.
+- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, over the direct no-spend usage read with the account's stored token, so every account is attempted about once per three ticks per pooled account, or once per `policy.usagePollTtlMs` plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. The usage endpoint rate limits each account on its own and names the time to come back in the `retry-after` of its HTTP 429; that time is stored as `usageRetryAt`, and no sampler (the tick, `status`, the seat's in-decision sample) reads the account before it. An expired stored access token stays unmeasured until a session on that store refreshes it.
 - The depleted pause happens at the bar, not at 100; Codex has no pause and rides its account until the server refuses it, because a running sibling cannot adopt another account without restarting.
 - Neither pool has a post-swap cooldown or a manual `switch`: a move is a respawn of one session under a fixed store, so nothing another session reads is invalidated by it, and placement at launch replaces the manual pick.
 

package/README.md

@@ -73,6 +73,7 @@ claude                  # use claude as always; each session gets its own accoun
 | `tokenmaxxing check` | fold fresh tees, sample up to three stale accounts, and self-update a Bun global install once a day; the periodic timer runs this every tick |
 | `tokenmaxxing doctor` | verify the install: PATH order, `claudeBin`, the five settings entries, the timer, the credential identity of every Codex store and of every Claude store whose access token is still fresh (an expiring Claude token is reported as unverifiable, not as a failure), codex hook trust, setup-token age, and shell aliases that shadow `claude` |
 | `tokenmaxxing rename [--codex \| --grok \| --opencode-go] <sel> <label>` / `rm [...] <sel>` | manage a pool (one email can hold both a claude and a codex account); `rm` is refused for an account with a running supervised session |
+| `tokenmaxxing serve` | serve the CLIProxyAPI-compatible usage API on `http://localhost:8317` (`hub.port`) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows the quota of every pooled Claude and Codex account; the management key is the contents of `hub-key` in the state directory, minted on the first run. Details in [Usage hub](docs/content/docs/hub.mdx) |
 | `tokenmaxxing uninstall [--yes]` | print the targets, then remove the shims, settings entries, codex Stop hook, check timer, and rc PATH line (accounts/stores kept); refused without `--yes` when `HOME` is the login home |
 | `tokenmaxxing setup-token [--print \| rm <label\|uuid>]` | Cursor Cloud only: mint one `claude setup-token` per pooled account (a browser sign-in each) and print the `TOKENMAXXING_TOKENS` secret value; `--print` prints the stored set, `rm` drops one |
 | `tokenmaxxing cursor init [dir]` | write the Claude relay subagent and `.cursor/environment.json` into a repo |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.64.0",
+  "version": "1.66.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/cli/serve.ts

@@ -0,0 +1,222 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { sortBy } from "es-toolkit";
+import { z } from "zod";
+import { writeFileAtomic } from "../lib/atomic.ts";
+import { claude } from "../lib/claude.ts";
+import { codex, observeCodex } from "../lib/codex.ts";
+import { CODEX_USAGE_URL } from "../lib/codexusage.ts";
+import { errorMessage, log } from "../lib/log.ts";
+import { paths } from "../lib/paths.ts";
+import { isExhausted, thresholdBars } from "../lib/picker.ts";
+import type { Provider } from "../lib/provider.ts";
+import { foldTee } from "../lib/sample.ts";
+import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { OAUTH_USAGE_URL } from "../lib/usage.ts";
+import type { Account, Config } from "../lib/types.ts";
+import { c, emitError } from "./render.ts";
+import { usageReport, type UsageReport, type WindowReport } from "./status.ts";
+
+const MANAGEMENT_PREFIX = "/v0/management/";
+const STALE_AFTER_MS = 2 * 60 * 60_000;
+
+type HubPool = {
+  provider: Provider;
+  usageUrl: string;
+  fold: (account: Account) => void;
+  read: (account: Account, cfg: Config, now: number) => Promise<Account>;
+  body: (usage: UsageReport, account: Account) => unknown;
+};
+
+function iso(epochMs: number | null): string | null {
+  return epochMs == null ? null : new Date(epochMs).toISOString();
+}
+
+function claudeBody(usage: UsageReport): unknown {
+  const win = (w: WindowReport | null) => (w ? { utilization: w.usedPercentage, resets_at: iso(w.resetsAt) } : null);
+  return {
+    five_hour: win(usage.fiveHour),
+    seven_day: win(usage.week),
+    limits: usage.limits.map((w) => ({ kind: "weekly_scoped", percent: w.usedPercentage, resets_at: iso(w.resetsAt), scope: { model: { display_name: w.name } } })),
+  };
+}
+
+function codexBody(usage: UsageReport, account: Account): unknown {
+  const win = (w: WindowReport | undefined) =>
+    w
+      ? {
+          used_percent: w.usedPercentage,
+          reset_at: w.resetsAt == null ? null : Math.round(w.resetsAt / 1000),
+          ...(w.windowSeconds == null ? {} : { limit_window_seconds: w.windowSeconds }),
+        }
+      : null;
+  const pair = (windows: WindowReport[]) => {
+    const ordered = sortBy(windows, [(w) => w.windowSeconds ?? Number.POSITIVE_INFINITY]);
+    return { primary_window: win(ordered[0]), secondary_window: win(ordered[1]) };
+  };
+  const named = new Map<string, WindowReport[]>();
+  for (const w of usage.limits) named.set(w.name, [...(named.get(w.name) ?? []), w]);
+  return {
+    ...(account.tier ? { plan_type: account.tier } : {}),
+    rate_limit: pair([usage.fiveHour, usage.week].filter((w) => w != null)),
+    ...(named.size === 0 ? {} : { additional_rate_limits: [...named].map(([limit_name, windows]) => ({ limit_name, rate_limit: pair(windows) })) }),
+  };
+}
+
+const POOLS: HubPool[] = [
+  {
+    provider: claude,
+    usageUrl: OAUTH_USAGE_URL,
+    fold: foldTee,
+    read: async (account) => account,
+    body: claudeBody,
+  },
+  {
+    provider: codex,
+    usageUrl: CODEX_USAGE_URL,
+    fold: () => {},
+    read: async (account, cfg, now) => {
+      await observeCodex(account, cfg, now, { probe: true, refresh: false });
+      return loadAccounts(codex.pool).accounts.find((a) => a.id === account.id) ?? account;
+    },
+    body: codexBody,
+  },
+];
+
+function authIndex(pool: HubPool, account: Account): string {
+  return new Bun.CryptoHasher("sha256").update(`${pool.provider.name}:${account.id}`).digest("hex").slice(0, 16);
+}
+
+function json(value: unknown, status = 200): Response {
+  return Response.json(value, { status });
+}
+
+function authFiles(cfg: Config, now: number): unknown {
+  const files = POOLS.flatMap((pool) => {
+    const ctx = { now, thresholds: thresholdBars(cfg), currentId: null, families: pool.provider.gatedFamilies(cfg), seats: null };
+    return loadAccounts(pool.provider.pool).accounts.map((a) => {
+      pool.fold(a);
+      return {
+        id: a.id,
+        auth_index: authIndex(pool, a),
+        name: a.label,
+        type: pool.provider.name,
+        provider: pool.provider.name,
+        label: a.label,
+        ...(a.email ? { email: a.email } : {}),
+        status: a.needsReauth === true ? "error" : "active",
+        status_message: a.needsReauth === true ? `needs reauth - run \`tokenmaxxing auth${pool.provider.flag} ${a.label}\`` : "",
+        disabled: false,
+        unavailable: isExhausted(a, ctx),
+      };
+    });
+  });
+  return { observed_at: new Date(now).toISOString(), files };
+}
+
+const ApiCallSchema = z.looseObject({
+  auth_index: z.string().optional(),
+  authIndex: z.string().optional(),
+  AuthIndex: z.string().optional(),
+  method: z.string().optional(),
+  url: z.string().optional(),
+});
+
+async function apiCall(req: Request): Promise<Response> {
+  const parsed = ApiCallSchema.safeParse(await req.json().catch(() => undefined));
+  if (!parsed.success) return json({ error: "invalid body" }, 400);
+  const call = parsed.data;
+  const method = (call.method ?? "").trim().toUpperCase();
+  if (method === "") return json({ error: "missing method" }, 400);
+  if (!call.url) return json({ error: "missing url" }, 400);
+  let target: URL;
+  try {
+    target = new URL(call.url);
+  } catch {
+    return json({ error: "invalid url" }, 400);
+  }
+  const pool = POOLS.find((p) => p.usageUrl === `${target.origin}${target.pathname}`);
+  if (method !== "GET" || !pool) {
+    return json({ error: `unsupported request: this hub serves ${POOLS.map((p) => `GET ${p.usageUrl}`).join(" and ")} only` }, 400);
+  }
+  const index = call.auth_index ?? call.authIndex ?? call.AuthIndex ?? "";
+  const account = loadAccounts(pool.provider.pool).accounts.find((a) => authIndex(pool, a) === index);
+  if (!account) return json({ error: "auth credential not found for auth_index" }, 400);
+  const now = Date.now();
+  const current = await pool.read(account, loadConfig(), now);
+  pool.fold(current);
+  const usage = usageReport({ ...current, windows: current.windows.filter((w) => now - w.sampledAt <= STALE_AFTER_MS) }, now);
+  if (!usage || (!usage.fiveHour && !usage.week)) return json({ error: `no usage figure newer than ${STALE_AFTER_MS / 3_600_000}h for this account` }, 502);
+  return json({ status_code: 200, header: { "Content-Type": ["application/json"] }, body: JSON.stringify(pool.body(usage, current)) });
+}
+
+function presentedKey(req: Request): string {
+  const auth = req.headers.get("authorization") ?? "";
+  if (auth !== "") {
+    const at = auth.indexOf(" ");
+    return at > 0 && auth.slice(0, at).toLowerCase() === "bearer" ? auth.slice(at + 1) : auth;
+  }
+  return req.headers.get("x-management-key") ?? "";
+}
+
+function keyMatches(presented: string, key: string): boolean {
+  const a = Buffer.from(presented);
+  const b = Buffer.from(key);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+async function handle(req: Request, key: string): Promise<Response> {
+  const url = new URL(req.url);
+  if (!url.pathname.startsWith(MANAGEMENT_PREFIX)) return json({ error: "not found" }, 404);
+  const presented = presentedKey(req);
+  if (presented === "") return json({ error: "missing management key" }, 401);
+  if (!keyMatches(presented, key)) return json({ error: "invalid management key" }, 401);
+  const route = url.pathname.slice(MANAGEMENT_PREFIX.length);
+  if (route === "auth-files" && req.method === "GET") return json(authFiles(loadConfig(), Date.now()));
+  if (route === "api-call" && req.method === "POST") return apiCall(req);
+  return json({ error: "not found" }, 404);
+}
+
+function managementKey(): string {
+  if (existsSync(paths.hubKeyFile)) {
+    const mode = statSync(paths.hubKeyFile).mode & 0o777;
+    if (mode & 0o077) throw new Error(`${paths.hubKeyFile} is mode ${mode.toString(8)}, readable by other local users - chmod 600 it`);
+    const key = readFileSync(paths.hubKeyFile, "utf8").trim();
+    if (key === "") throw new Error(`${paths.hubKeyFile} is empty - write a management key into it, or delete it and serve mints one`);
+    return key;
+  }
+  const key = randomBytes(32).toString("hex");
+  writeFileAtomic(paths.hubKeyFile, `${key}\n`);
+  log("hub.key_minted", { file: paths.hubKeyFile });
+  return key;
+}
+
+export async function cmdServe(args: string[]): Promise<number> {
+  if (args.length > 0) {
+    emitError({ message: `unknown serve option: ${args[0]} (serve takes no options; set hub.port in ${paths.configJson})` });
+    return 2;
+  }
+  const cfg = loadConfig();
+  const key = managementKey();
+  const server = Bun.serve({
+    hostname: "localhost",
+    port: cfg.hub.port,
+    fetch: (req) => handle(req, key),
+    error: (e) => {
+      log("hub.error", { err: errorMessage(e) });
+      return json({ error: "internal error" }, 500);
+    },
+  });
+  console.log(`${c.green("✓")} serving the CLIProxyAPI-compatible usage API at http://localhost:${server.port}/v0/management`);
+  console.log(c.dim(`management key: the contents of ${paths.hubKeyFile}`));
+  log("hub.started", { port: server.port });
+  return new Promise<number>((resolve) => {
+    const stop = (signal: string) => {
+      server.stop(true);
+      log("hub.stopped", { signal });
+      resolve(0);
+    };
+    process.once("SIGINT", () => stop("SIGINT"));
+    process.once("SIGTERM", () => stop("SIGTERM"));
+  });
+}

package/src/cli/status.ts

@@ -11,7 +11,9 @@ import type { Provider, SampleReport } from "../lib/provider.ts";
 import { bar, c, count, emitJson, fmtAgo } from "./render.ts";
 import type { Account, Config, Thresholds, Window } from "../lib/types.ts";
 
-type WindowReport = { usedPercentage: number; resetsAt: number | null; windowSeconds: number | null };
+export type WindowReport = { usedPercentage: number; resetsAt: number | null; windowSeconds: number | null };
+
+export type UsageReport = { fiveHour: WindowReport | null; week: WindowReport | null; limits: (WindowReport & { name: string })[] };
 
 type StatusAccount = {
   label: string;
@@ -22,7 +24,7 @@ type StatusAccount = {
   sessions: number;
   needsReauth: boolean;
   exhausted: boolean;
-  usage: { fiveHour: WindowReport | null; week: WindowReport | null; limits: (WindowReport & { name: string })[] } | null;
+  usage: UsageReport | null;
   usageAt: number | null;
   limitsAt: number | null;
   sample: SampleReport | { ok: true; source: "cached" };
@@ -47,7 +49,7 @@ function currentWindow(w: Window, now: number): WindowReport {
   };
 }
 
-function usageReport(a: Account, now: number): StatusAccount["usage"] {
+export function usageReport(a: Account, now: number): UsageReport | null {
   if (a.lastUsageAt == null) return null;
   const session = sessionWindow(a);
   const week = weeklyWindow(a);

package/src/lib/claude.ts

@@ -12,7 +12,7 @@ import { claudePool, env, paths, seatFromEnv, storeDirFor } from "./paths.ts";
 import { pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import { seatCounts } from "./presence.ts";
 import type { Observation, Provider, SampleReport } from "./provider.ts";
-import { foldTee, sampleAccountUsage, teeObservation } from "./sample.ts";
+import { foldTee, sampleAccountUsage, teeObservation, usageBlockedUntil } from "./sample.ts";
 import { clearUsageSnapshot, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, saveAccounts, type Harvest } from "./state.ts";
 import { loadSetupTokens, saveSetupTokens } from "./setuptokens.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
@@ -43,7 +43,7 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
   const probeAttempted = account.lastProbeAt != null && now - account.lastProbeAt <= interval;
   const snap = loadUsageSnapshot(account.id);
   const fresh = snap != null && now - snap.at <= ttl;
-  if (opts.probe && !probeAttempted && (!fresh || opts.perModel)) {
+  if (opts.probe && !probeAttempted && usageBlockedUntil(account, now) == null && (!fresh || opts.perModel)) {
     const startedAt = Date.now();
     const outcome = await sampleAccountUsage(account);
     await withLock(claudePool.lockFile, () => {
@@ -61,6 +61,7 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
         }
       } else {
         a.probeFails = (a.probeFails ?? 0) + 1;
+        if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
       }
       saveAccounts(claudePool, idx);
     });
@@ -82,6 +83,7 @@ async function samplePool(accounts: Account[]): Promise<Map<string, SampleReport
       }
       const outcome = await sampleAccountUsage(a);
       if (!outcome.ok) {
+        if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
         reports.set(a.id, { ok: false, reason: outcome.reason });
         return;
       }
@@ -215,7 +217,7 @@ async function login(): Promise<Harvest | null> {
 
     console.log(c.dim("sampling usage..."));
     const sampled = await fetchUsageDirect(blob.claudeAiOauth.accessToken);
-    if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+    if (!sampled.ok) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
     const at = Date.now();
     const id = oauthAccount.accountUuid;
     return {
@@ -223,7 +225,8 @@ async function login(): Promise<Harvest | null> {
       email: oauthAccount.emailAddress,
       tier: claudeTierLabel(blob.claudeAiOauth),
       oauthAccount,
-      sample: sampled ? { windows: windowsOf(sampled, at), at } : null,
+      sample: sampled.ok ? { windows: windowsOf(sampled.usage, at), at } : null,
+      ...(!sampled.ok && sampled.retryAt != null ? { usageRetryAt: sampled.retryAt } : {}),
       park: () => writeItem(storeTarget(id), claudeAiOauthOnly(blobRaw)),
     };
   } finally {

package/src/lib/codexusage.ts

@@ -6,7 +6,8 @@ import { JsonTextSchema, type CodexAuthJson, type CodexUsage, type Window } from
 import { codexIdentityOf } from "./codexauth.ts";
 import { familyTokens } from "./usage.ts";
 
-const USAGE_URL = env("TOKENMAXXING_CODEX_USAGE_URL", "https://chatgpt.com/backend-api/wham/usage");
+export const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const USAGE_URL = env("TOKENMAXXING_CODEX_USAGE_URL", CODEX_USAGE_URL);
 
 export class CodexUsageReadError extends Error {
   constructor(detail: string) {

package/src/lib/paths.ts

@@ -33,6 +33,7 @@ export const paths = {
   cloudSessionsJson: join(TM_HOME, "cloud", "sessions.json"),
   cloudWalledJson: join(TM_HOME, "cloud", "walled.json"),
   cloudLockFile: join(TM_HOME, "cloud", "lock"),
+  hubKeyFile: join(TM_HOME, "hub-key"),
 
   claudeSettings: env(
     "TOKENMAXXING_CLAUDE_SETTINGS",

package/src/lib/sample.ts

@@ -9,7 +9,7 @@ import { loadAccounts, loadUsageSnapshot, saveAccounts } from "./state.ts";
 import { fetchUsageDirect, mergeWindows, windowsOf } from "./usage.ts";
 import type { Account, Config, UsageWindows } from "./types.ts";
 
-export type SampleOutcome = { ok: true; usage: UsageWindows; via: "get" } | { ok: false; reason: string };
+export type SampleOutcome = { ok: true; usage: UsageWindows; via: "get" } | { ok: false; reason: string; retryAt?: number };
 
 type PreparedSample = { ok: true; token: string | null } | { ok: false; reason: string };
 
@@ -48,13 +48,26 @@ export async function prepareSample(account: Account): Promise<PreparedSample> {
   return { ok: true, token: creds.accessToken };
 }
 
+export function usageBlockedUntil(account: Account, now: number): number | null {
+  return account.usageRetryAt != null && account.usageRetryAt > now ? account.usageRetryAt : null;
+}
+
+function rateLimitedReason(retryAt: number, now: number): string {
+  return `the usage endpoint rate limited this account, next read in ${Math.ceil((retryAt - now) / 60_000)}m`;
+}
+
 export async function runSample(account: Account, token: string | null): Promise<SampleOutcome> {
   if (!token) return { ok: false, reason: "no usable access token in the store - run `tokenmaxxing auth`" };
-  const usage = await fetchUsageDirect(token);
-  return usage ? { ok: true, usage, via: "get" } : { ok: false, reason: "usage read failed (see log)" };
+  const read = await fetchUsageDirect(token);
+  if (read.ok) return { ok: true, usage: read.usage, via: "get" };
+  if (read.retryAt == null) return { ok: false, reason: "usage read failed (see log)" };
+  return { ok: false, reason: rateLimitedReason(read.retryAt, Date.now()), retryAt: read.retryAt };
 }
 
 export async function sampleAccountUsage(account: Account): Promise<SampleOutcome> {
+  const now = Date.now();
+  const blockedUntil = usageBlockedUntil(account, now);
+  if (blockedUntil != null) return { ok: false, reason: rateLimitedReason(blockedUntil, now) };
   const prepared = await prepareSample(account);
   return prepared.ok ? runSample(account, prepared.token) : prepared;
 }
@@ -89,7 +102,7 @@ export async function sampleOldest(cfg: Config): Promise<void> {
         continue;
       }
       target.storeFails = 0;
-      batch.push({ account: target, token: prepared.token });
+      if (usageBlockedUntil(target, now) == null) batch.push({ account: target, token: prepared.token });
     }
     saveAccounts(claudePool, idx);
     return batch;
@@ -106,6 +119,10 @@ export async function sampleOldest(cfg: Config): Promise<void> {
           stored.needsReauth = true;
           dirty = true;
         }
+        if (stored && !outcome.ok && outcome.retryAt != null) {
+          stored.usageRetryAt = outcome.retryAt;
+          dirty = true;
+        }
         if (stored && outcome.ok && (stored.lastUsageAt == null || startedAt > stored.lastUsageAt)) {
           stored.windows = mergeWindows(windowsOf(outcome.usage, startedAt), stored.windows);
           stored.lastUsageAt = startedAt;

package/src/lib/state.ts

@@ -73,6 +73,7 @@ export type Harvest = {
   tier: string | null;
   oauthAccount?: Account["oauthAccount"];
   sample: { windows: Window[]; at: number } | null;
+  usageRetryAt?: number;
   park: () => Promise<void>;
 };
 
@@ -92,6 +93,7 @@ export function upsertAccount(
     lastUsageAt: h.sample ? h.sample.at : existing?.lastUsageAt,
     needsReauth: false,
     ...(h.oauthAccount ? { oauthAccount: h.oauthAccount } : {}),
+    usageRetryAt: h.sample ? undefined : (h.usageRetryAt ?? existing?.usageRetryAt),
   };
   if (existing) Object.assign(existing, fresh);
   else idx.accounts.push(fresh);

package/src/lib/types.ts

@@ -69,6 +69,7 @@ export const AccountSchema = z.object({
   lastProbeAt: z.number().optional(),
   probeFails: z.number().optional(),
   storeFails: z.number().optional(),
+  usageRetryAt: z.number().optional(),
   enforcedUntil: z.number().optional(),
   needsReauth: z.boolean().optional(),
   oauthAccount: OAuthAccountSchema.optional(),
@@ -115,6 +116,11 @@ export const ConfigSchema = z
         checkIntervalMs: z.number().int().min(10_000).default(60_000),
       })
       .prefault({}),
+    hub: z
+      .object({
+        port: z.number().int().min(1).max(65_535).default(8317),
+      })
+      .prefault({}),
   })
   .refine((cfg) => cfg.policy.projectionMargin < cfg.thresholds.session, {
     path: ["policy", "projectionMargin"],

package/src/lib/usage.ts

@@ -181,7 +181,8 @@ export function scrubCredentialEnv(env: Record<string, string>): Record<string,
   return scrubbed;
 }
 
-const USAGE_URL = env("TOKENMAXXING_OAUTH_USAGE_URL", "https://api.anthropic.com/api/oauth/usage");
+export const OAUTH_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const USAGE_URL = env("TOKENMAXXING_OAUTH_USAGE_URL", OAUTH_USAGE_URL);
 const USAGE_DEADLINE_MS = 10_000;
 
 const ResetsAtSchema = z.iso.datetime({ offset: true }).transform((iso) => Date.parse(iso)).nullish();
@@ -208,7 +209,11 @@ function scopedRows(limits: unknown[]): Record<string, UsageWindow> {
   return perModel;
 }
 
-export async function fetchUsageDirect(accessToken: string): Promise<UsageWindows | null> {
+const RetryAfterSecondsSchema = z.coerce.number().int().positive();
+
+export type UsageRead = { ok: true; usage: UsageWindows } | { ok: false; retryAt: number | null };
+
+export async function fetchUsageDirect(accessToken: string): Promise<UsageRead> {
   let res: Response;
   try {
     res = await http.get(USAGE_URL, {
@@ -218,17 +223,18 @@ export async function fetchUsageDirect(accessToken: string): Promise<UsageWindow
     });
   } catch (e) {
     log("usage.get_failed", { err: errorMessage(e) });
-    return null;
+    return { ok: false, retryAt: null };
   }
   if (!res.ok) {
-    log("usage.get_failed", { status: res.status });
-    return null;
+    const retryAfter = res.status === 429 ? RetryAfterSecondsSchema.safeParse(res.headers.get("retry-after")).data : undefined;
+    log("usage.get_failed", { status: res.status, retryAfter });
+    return { ok: false, retryAt: retryAfter != null ? Date.now() + retryAfter * 1000 : null };
   }
   const parsed = UsageResponseSchema.safeParse(JsonTextSchema.safeParse(await res.text()).data);
   if (!parsed.success || !parsed.data.five_hour || !parsed.data.seven_day) {
     log("usage.get_incomplete", { ok: parsed.success, issue: parsed.success ? undefined : z.prettifyError(parsed.error).slice(0, 200) });
-    return null;
+    return { ok: false, retryAt: null };
   }
   const win = (w: z.infer<typeof UsageLimitSchema>): UsageWindow => ({ usedPercentage: w.utilization, resetsAt: w.resets_at ?? null });
-  return { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []) };
+  return { ok: true, usage: { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []) } };
 }

package/src/main.ts

@@ -25,6 +25,7 @@ import { cmdSeat } from "./cli/seat.ts";
 import { cmdSetupToken } from "./cli/setuptoken.ts";
 import { cmdCloudRun } from "./cli/cloudrun.ts";
 import { cmdCursorInit } from "./cli/cursorinit.ts";
+import { cmdServe } from "./cli/serve.ts";
 import { onLoginHome, timerDeactivationHint, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
 import { errorMessage } from "./lib/log.ts";
 import { HOME } from "./lib/paths.ts";
@@ -58,6 +59,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing rename")} [--codex | --grok | --opencode-go] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex | --grok | --opencode-go] <sel>
   ${c.cyan("tokenmaxxing seat --codex")} <pid>  borrow one pooled codex account for an unattended consumer (plugin, script): prints the CODEX_HOME to set, reserved until <pid> exits; exit 1 = none usable, fall back to the ambient login
+  ${c.cyan("tokenmaxxing serve")}      serve the CLIProxyAPI-compatible usage API on http://localhost:<hub.port> (default 8317) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows every pooled Claude and Codex account's quota; the management key is the contents of hub-key in the state directory
   ${c.cyan("tokenmaxxing uninstall")} [--yes]  print the targets, then remove supervisor + settings entries (refused without ${c.cyan("--yes")} when HOME is the login home)
   ${c.cyan("tokenmaxxing setup-token")} [--print | rm <label|uuid>]  Cursor Cloud only: mint one \`claude setup-token\` per pooled account (browser sign-in each) and print the TOKENMAXXING_TOKENS secret value; ${c.cyan("--print")} prints the stored set, ${c.cyan("rm")} drops one
   ${c.cyan("tokenmaxxing cursor init")} [dir]  write the Claude relay subagent (.cursor/agents/claude.md) and .cursor/environment.json into a repo
@@ -161,6 +163,7 @@ async function main(): Promise<number> {
       return cmdSeat(args[1], args.slice(2));
     }
     case "setup-token": return cmdSetupToken(args.slice(1));
+    case "serve": return cmdServe(args.slice(1));
     case "cursor": {
       if (args[1] === "init") return cmdCursorInit(args.slice(2));
       emitError({ message: "usage: tokenmaxxing cursor init [dir]" });