tokenmaxxing 1.65.0 → 1.67.0

package/DESIGN.md

@@ -38,12 +38,13 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
   - `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.
+- A usage hub service (`com.tokenmaxxing.hub` launchd agent on macOS, `tokenmaxxing-hub.service` systemd user service on Linux) running `tokenmaxxing serve`, so the [usage hub](docs/content/docs/hub.mdx) is up in the background beside the check timer.
 
-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 in the switching path. The [usage hub](docs/content/docs/hub.mdx) that answers the CLIProxyAPI management subset for a dashboard from the cached figures runs outside the switching path, as a background service beside the check timer (`tokenmaxxing serve` runs the same server in the foreground). The `claude` binary, `~/.claude.json`, and Claude Code's default credential store are untouched; inside `~/.claude` only `settings.json` gets the five entries.
 
 ---
 

package/README.md

@@ -52,7 +52,7 @@ programs.tokenmaxxing.package = inputs.tokenmaxxing.packages.${pkgs.system}.defa
 
 With either module, run `tokenmaxxing init` afterwards.
 
-`init` verifies and pins the real `claude` binary, opens an isolated `claude` session for your first pooled account (run `/login` there, even if you are already signed in; the login you already have stays for sessions started outside the supervisor), installs the `claude` supervisor and the `xx` entry point, five `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a StopFailure hook, a SessionStart hook), and the periodic check timer, and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
+`init` verifies and pins the real `claude` binary, opens an isolated `claude` session for your first pooled account (run `/login` there, even if you are already signed in; the login you already have stays for sessions started outside the supervisor), installs the `claude` supervisor and the `xx` entry point, five `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a StopFailure hook, a SessionStart hook), the periodic check timer, and the usage hub service, and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
 
 ```sh
 tokenmaxxing add        # logs one in, in isolation, into its own store
@@ -63,7 +63,7 @@ claude                  # use claude as always; each session gets its own accoun
 
 | command | what it does |
 |---|---|
-| `tokenmaxxing init` | verify and pin the real `claude`, log the first account in (isolated) + install supervisor, hooks, PATH line, and check timer |
+| `tokenmaxxing init` | verify and pin the real `claude`, log the first account in (isolated) + install supervisor, hooks, PATH line, check timer, and hub service |
 | `tokenmaxxing init --codex` | same for codex: log in the first account (isolated), install codex supervisor + Stop hook |
 | `tokenmaxxing init --grok` / `init --opencode-go` | pool the first grok login or opencode-go key, status-only: no supervisor, no switching |
 | `tokenmaxxing add [--codex \| --grok \| --opencode-go]` | register an additional account in that pool (isolated login, harvested once into its own store) |
@@ -71,9 +71,10 @@ claude                  # use claude as always; each session gets its own accoun
 | `tokenmaxxing status [--cached]` | every pool: accounts with 5h / weekly / per-model usage bars, live session counts, exhausted-until-reset; `--cached` renders the stored figures without sampling |
 | `tokenmaxxing config` | the config path and the effective values; edit the file in an editor, a bad value fails the next load with the field name |
 | `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 doctor` | verify the install: PATH order, `claudeBin`, the five settings entries, the timer, the hub service, 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 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 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, and `init` runs it as a background service beside the check timer. 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, hub service, 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 |
 | `tokenmaxxing cloud run [--session <id>] [--max-turns <n>] "<prompt>"` | on a Cursor Cloud VM: run `claude -p` on a setup token, rotate to the next token on a usage limit |
@@ -114,7 +115,7 @@ See [How switching decides](docs/content/docs/switching.mdx) for the policy and
 
 `thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `projectionMargin` is a fixed safety margin subtracted from the session bar only (default 3), so a large turn is less likely to blow past the 5-hour bar between checks; the weekly bar takes no margin because one turn cannot overshoot a week; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is how long a usage sample stays fresh, for a seat's own sample and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers); `checkIntervalMs` is the periodic check tick (default 60s), which `init` writes into the timer - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick. `claudeBin`, `codexBin`, `grokBin`, and `opencodeBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, and `TOKENMAXXING_OPENCODE_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
 
-State lives in `~/.config/tokenmaxxing/`; outside it the install touches Claude Code's `settings.json`, codex's `hooks.json`, the timer unit, and your shell rc. Each account's credential store is `stores/<uuid8>/`, which Claude Code reads and refreshes as its own: on macOS the credential is a login-keychain item keyed by the store path (never plaintext on disk), on Linux a 0600 `.credentials.json` inside the store (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
+State lives in `~/.config/tokenmaxxing/`; outside it the install touches Claude Code's `settings.json`, codex's `hooks.json`, the timer and usage hub units, and your shell rc. Each account's credential store is `stores/<uuid8>/`, which Claude Code reads and refreshes as its own: on macOS the credential is a login-keychain item keyed by the store path (never plaintext on disk), on Linux a 0600 `.credentials.json` inside the store (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 
 ## Codex support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.65.0",
+  "version": "1.67.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/doctor.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { verifyRealClaude } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
-import { checkTimerHealthy, codexStoreHookTrust, findClaudeShadowers, isBinDirAhead, shellRcPath, timerActivationHint } from "../lib/install.ts";
+import { checkTimerHealthy, codexStoreHookTrust, findClaudeShadowers, hubServiceHealthy, isBinDirAhead, shellRcPath, skipImperativeHub, timerActivationHint } from "../lib/install.ts";
 import { errorMessage } from "../lib/log.ts";
 import { claudePool, codexPool, paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
@@ -31,6 +31,10 @@ export async function cmdDoctor(): Promise<number> {
   check(s.stopFailureOk, "StopFailure hook installed in settings.json", "run `tokenmaxxing init`");
   check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
   check(checkTimerHealthy(), "periodic check timer active", timerActivationHint());
+  if (existsSync(paths.supervisorLink)) {
+    if (skipImperativeHub()) note("usage hub service is owned outside init (TOKENMAXXING_SKIP_HUB set) - not verified here");
+    else check(hubServiceHealthy(), "usage hub service active", "run `tokenmaxxing init` (it writes the unit and activates it)");
+  }
 
   const idx = loadAccounts(claudePool);
   check(idx.accounts.length > 0, "at least one account in the pool", "run `tokenmaxxing init`");

package/src/cli/serve.ts

@@ -0,0 +1,229 @@
+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 { hubDeactivationHint } from "../lib/install.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();
+  let server: ReturnType<typeof Bun.serve>;
+  try {
+    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);
+      },
+    });
+  } catch (e) {
+    emitError({ message: `cannot bind localhost:${cfg.hub.port}: ${errorMessage(e)} (another \`tokenmaxxing serve\` or the usage hub service may already hold the port - stop it first: ${hubDeactivationHint()})` });
+    return 1;
+  }
+  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

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { readItem, writeItem, deleteItem, isolatedTarget, readStore, storeTarget, claudeAiOauthOnly } from "./credstore.ts";
 import { resolveRealClaude, resolveVerifiedClaude } from "./claudebin.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
-import { ensurePathInRc, installSupervisor, managedShellRcSkipLines, shellRcPath, timerActivationHint } from "./install.ts";
+import { ensurePathInRc, hubActivationHint, installSupervisor, managedShellRcSkipLines, shellRcPath, timerActivationHint } from "./install.ts";
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isDeadCredential, InvalidGrantError } from "./oauth.ts";
@@ -270,6 +270,8 @@ function install(): void {
   console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/StopFailure/SessionStart hooks`);
   if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every ${out.checkIntervalS}s)`);
   else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
+  if (out.hubLoaded) console.log(`${c.green("✓")} usage hub service active`);
+  else console.log(c.yellow(`⚠ usage hub service written but not activated - run: ${hubActivationHint()}`));
   if (!out.pathAhead) {
     console.log();
     ensurePathAhead();

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/install.ts

@@ -9,7 +9,7 @@ import { resolveRealClaude } from "./claudebin.ts";
 import { loadConfig } from "./state.ts";
 import { ErrnoSchema } from "./types.ts";
 
-export type InstallOutcome = { claudeWrapper: string; installedBin: string; pathAhead: boolean; timerLoaded: boolean; checkIntervalS: number };
+export type InstallOutcome = { claudeWrapper: string; installedBin: string; pathAhead: boolean; timerLoaded: boolean; hubLoaded: boolean; checkIntervalS: number };
 
 export function isBinDirAhead(): boolean {
   const dirs = (process.env.PATH ?? "").split(":");
@@ -39,6 +39,10 @@ export function skipImperativeTimer(): boolean {
   return envFlag("TOKENMAXXING_SKIP_TIMER");
 }
 
+export function skipImperativeHub(): boolean {
+  return envFlag("TOKENMAXXING_SKIP_HUB");
+}
+
 function isNixStorePath(path: string): boolean {
   return path === "/nix/store" || path.startsWith("/nix/store/");
 }
@@ -103,6 +107,7 @@ export function installSupervisor(): InstallOutcome {
     installedBin: target,
     pathAhead: isBinDirAhead(),
     timerLoaded: installCheckTimer(checkIntervalS),
+    hubLoaded: installHubService(),
     checkIntervalS,
   };
 }
@@ -203,9 +208,11 @@ export function uninstallCodexSupervisor(): void {
 }
 
 const LAUNCHD_LABEL = "com.tokenmaxxing.check";
+const LAUNCHD_HUB_LABEL = "com.tokenmaxxing.hub";
+const HUB_UNIT = "tokenmaxxing-hub.service";
 
-function launchdPlist(): string {
-  return join(paths.launchdAgentsDir, `${LAUNCHD_LABEL}.plist`);
+function launchdPlist(label: string): string {
+  return join(paths.launchdAgentsDir, `${label}.plist`);
 }
 
 function launchdDomain(): string | null {
@@ -221,11 +228,19 @@ function run(cmd: string[]): boolean {
   }
 }
 
+function systemdEnv(): string {
+  return `Environment="TOKENMAXXING_HOME=${paths.home.replaceAll("%", "%%")}"\n`;
+}
+
+function launchdEnv(): string {
+  return `  <key>EnvironmentVariables</key><dict><key>TOKENMAXXING_HOME</key><string>${escape(paths.home)}</string></dict>\n`;
+}
+
 function installCheckTimer(intervalS: number): boolean {
   if (skipImperativeTimer()) return true;
 
   if (process.platform === "darwin") {
-    const plist = launchdPlist();
+    const plist = launchdPlist(LAUNCHD_LABEL);
     writeFileAtomic(
       plist,
       `<?xml version="1.0" encoding="UTF-8"?>
@@ -235,7 +250,7 @@ function installCheckTimer(intervalS: number): boolean {
   <key>Label</key><string>${LAUNCHD_LABEL}</string>
   <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string></array>
   <key>StartInterval</key><integer>${intervalS}</integer>
-  <key>StandardOutPath</key><string>/dev/null</string>
+${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
   <key>StandardErrorPath</key><string>${escape(join(paths.home, "check.stderr.log"))}</string>
 </dict>
 </plist>
@@ -257,7 +272,7 @@ Description=tokenmaxxing account-switch check
 [Service]
 Type=oneshot
 ExecStart=${exec}
-`,
+${systemdEnv()}`,
     0o644,
   );
   writeFileAtomic(
@@ -283,16 +298,23 @@ WantedBy=timers.target
 
 export function timerActivationHint(): string {
   if (process.platform === "darwin") {
-    return `launchctl bootstrap gui/$(id -u) ${launchdPlist()}`;
+    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(LAUNCHD_LABEL)}`;
   }
   return "systemctl --user daemon-reload && systemctl --user enable --now tokenmaxxing-check.timer";
 }
 
+export function hubActivationHint(): string {
+  if (process.platform === "darwin") {
+    return `launchctl bootstrap gui/$(id -u) ${launchdPlist(LAUNCHD_HUB_LABEL)}`;
+  }
+  return `systemctl --user daemon-reload && systemctl --user enable --now ${HUB_UNIT}`;
+}
+
 export function checkTimerHealthy(): boolean {
   if (skipImperativeTimer()) return true;
   if (process.platform === "darwin") {
     const domain = launchdDomain();
-    return existsSync(launchdPlist()) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`]);
+    return existsSync(launchdPlist(LAUNCHD_LABEL)) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`]);
   }
   return (
     existsSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer")) &&
@@ -300,6 +322,15 @@ export function checkTimerHealthy(): boolean {
   );
 }
 
+export function hubServiceHealthy(): boolean {
+  if (skipImperativeHub()) return true;
+  if (process.platform === "darwin") {
+    const domain = launchdDomain();
+    return existsSync(launchdPlist(LAUNCHD_HUB_LABEL)) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_HUB_LABEL}`]);
+  }
+  return existsSync(join(paths.systemdUserDir, HUB_UNIT)) && run(["systemctl", "--user", "is-active", "--quiet", HUB_UNIT]);
+}
+
 export function timerDeactivationHint(): string {
   if (process.platform === "darwin") {
     return `launchctl bootout gui/$(id -u)/${LAUNCHD_LABEL}`;
@@ -307,11 +338,18 @@ export function timerDeactivationHint(): string {
   return "systemctl --user disable --now tokenmaxxing-check.timer";
 }
 
-function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
+export function hubDeactivationHint(): string {
+  if (process.platform === "darwin") {
+    return `launchctl bootout gui/$(id -u)/${LAUNCHD_HUB_LABEL}`;
+  }
+  return `systemctl --user disable --now ${HUB_UNIT}`;
+}
+
+function launchdJobLoaded(label: string): "loaded" | "not-loaded" | "unavailable" {
   const domain = launchdDomain();
   if (domain == null) return "unavailable";
   try {
-    const { exitCode } = Bun.spawnSync(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`], { stdout: "ignore", stderr: "ignore", timeout: 10_000 });
+    const { exitCode } = Bun.spawnSync(["launchctl", "print", `${domain}/${label}`], { stdout: "ignore", stderr: "ignore", timeout: 10_000 });
     if (exitCode === 0) return "loaded";
     return exitCode === 113 ? "not-loaded" : "unavailable";
   } catch {
@@ -319,9 +357,9 @@ function launchdJobLoaded(): "loaded" | "not-loaded" | "unavailable" {
   }
 }
 
-function systemdTimerActive(): "active" | "not-active" | "unavailable" {
+function systemdUnitActive(unit: string): "active" | "not-active" | "unavailable" {
   try {
-    const proc = Bun.spawnSync(["systemctl", "--user", "is-active", "tokenmaxxing-check.timer"], { stdout: "pipe", stderr: "ignore", timeout: 10_000 });
+    const proc = Bun.spawnSync(["systemctl", "--user", "is-active", unit], { stdout: "pipe", stderr: "ignore", timeout: 10_000 });
     const state = proc.stdout.toString().trim();
     if (state === "active" || state === "activating" || state === "reloading") return "active";
     if (state === "inactive" || state === "failed" || state === "deactivating" || state === "unknown" || state === "maintenance") return "not-active";
@@ -333,16 +371,16 @@ function systemdTimerActive(): "active" | "not-active" | "unavailable" {
 
 function removeTimerUnits(): void {
   if (process.platform === "darwin") {
-    rmSync(launchdPlist(), { force: true });
+    rmSync(launchdPlist(LAUNCHD_LABEL), { force: true });
     return;
   }
   rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer"), { force: true });
   rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.service"), { force: true });
 }
 
-type TimerOutcome = "removed" | "skipped" | "still-loaded";
+type UnitOutcome = "removed" | "skipped" | "still-loaded";
 
-function uninstallCheckTimer(live: boolean): TimerOutcome {
+function uninstallCheckTimer(live: boolean): UnitOutcome {
   if (skipImperativeTimer()) return "skipped";
   if (!live) {
     removeTimerUnits();
@@ -350,18 +388,94 @@ function uninstallCheckTimer(live: boolean): TimerOutcome {
   }
   if (process.platform === "darwin") {
     const domain = launchdDomain();
-    const loaded = launchdJobLoaded();
+    const loaded = launchdJobLoaded(LAUNCHD_LABEL);
     const deactivated = loaded === "loaded" && domain != null ? run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]) : loaded === "not-loaded";
     removeTimerUnits();
     return deactivated ? "removed" : "still-loaded";
   }
-  const active = systemdTimerActive();
-  const deactivated = active === "active" ? run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]) : active === "not-active";
+  const active = systemdUnitActive("tokenmaxxing-check.timer");
+  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]) || active === "not-active");
   removeTimerUnits();
   run(["systemctl", "--user", "daemon-reload"]);
   return deactivated ? "removed" : "still-loaded";
 }
 
+function installHubService(): boolean {
+  if (skipImperativeHub()) return true;
+
+  if (process.platform === "darwin") {
+    const plist = launchdPlist(LAUNCHD_HUB_LABEL);
+    writeFileAtomic(
+      plist,
+      `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LAUNCHD_HUB_LABEL}</string>
+  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>serve</string></array>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>RunAtLoad</key><true/>
+${launchdEnv()}  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>${escape(join(paths.home, "hub.stderr.log"))}</string>
+</dict>
+</plist>
+`,
+      0o644,
+    );
+    const domain = launchdDomain();
+    if (domain == null) return false;
+    run(["launchctl", "bootout", `${domain}/${LAUNCHD_HUB_LABEL}`]);
+    return run(["launchctl", "bootstrap", domain, plist]) || hubServiceHealthy();
+  }
+
+  const exec = `"${installedBin().replaceAll("%", "%%")}" serve`;
+  writeFileAtomic(
+    join(paths.systemdUserDir, HUB_UNIT),
+    `[Unit]
+Description=tokenmaxxing usage hub
+StartLimitIntervalSec=0
+
+[Service]
+ExecStart=${exec}
+${systemdEnv()}Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`,
+    0o644,
+  );
+  return run(["systemctl", "--user", "daemon-reload"]) && run(["systemctl", "--user", "enable", "--now", HUB_UNIT]);
+}
+
+function removeHubUnits(): void {
+  if (process.platform === "darwin") {
+    rmSync(launchdPlist(LAUNCHD_HUB_LABEL), { force: true });
+    return;
+  }
+  rmSync(join(paths.systemdUserDir, HUB_UNIT), { force: true });
+}
+
+function uninstallHubService(live: boolean): UnitOutcome {
+  if (skipImperativeHub()) return "skipped";
+  if (!live) {
+    removeHubUnits();
+    return "removed";
+  }
+  if (process.platform === "darwin") {
+    const domain = launchdDomain();
+    const loaded = launchdJobLoaded(LAUNCHD_HUB_LABEL);
+    const deactivated = loaded === "loaded" && domain != null ? run(["launchctl", "bootout", `${domain}/${LAUNCHD_HUB_LABEL}`]) : loaded === "not-loaded";
+    removeHubUnits();
+    return deactivated ? "removed" : "still-loaded";
+  }
+  const active = systemdUnitActive(HUB_UNIT);
+  const deactivated = active !== "unavailable" && (run(["systemctl", "--user", "disable", "--now", HUB_UNIT]) || active === "not-active");
+  removeHubUnits();
+  run(["systemctl", "--user", "daemon-reload"]);
+  return deactivated ? "removed" : "still-loaded";
+}
+
 export function shellRcPath(): string | null {
   const override = optionalEnv("TOKENMAXXING_SHELL_RC");
   if (override != null) return override;
@@ -445,7 +559,7 @@ export function removePathFromRc(rc: string): boolean {
   return true;
 }
 
-export type UninstallOutcome = { timer: "removed" | "skipped" | "still-loaded"; pathLineRemoved: boolean };
+export type UninstallOutcome = { timer: UnitOutcome; hub: UnitOutcome; pathLineRemoved: boolean };
 
 export function loginHome(): string {
   const cmd = process.platform === "darwin" ? ["id", "-P"] : ["getent", "passwd", String(process.getuid?.() ?? "")];
@@ -462,13 +576,18 @@ export function onLoginHome(): boolean {
 export function uninstallTargets(live: boolean): string[] {
   const timer =
     process.platform === "darwin"
-      ? `${launchdPlist()}${live ? ` (and launchctl bootout gui/${process.getuid?.() ?? "?"}/${LAUNCHD_LABEL})` : ""}`
+      ? `${launchdPlist(LAUNCHD_LABEL)}${live ? ` (and launchctl bootout gui/${process.getuid?.() ?? "?"}/${LAUNCHD_LABEL})` : ""}`
       : `${join(paths.systemdUserDir, "tokenmaxxing-check.timer")} and .service${live ? " (and systemctl --user disable --now tokenmaxxing-check.timer)" : ""}`;
+  const hub =
+    process.platform === "darwin"
+      ? `${launchdPlist(LAUNCHD_HUB_LABEL)}${live ? ` (and launchctl bootout gui/${process.getuid?.() ?? "?"}/${LAUNCHD_HUB_LABEL})` : ""}`
+      : `${join(paths.systemdUserDir, HUB_UNIT)}${live ? ` (and systemctl --user disable --now ${HUB_UNIT})` : ""}`;
   const rc = shellRcPath();
   return [
     `${paths.claudeSettings}: the hook and statusline entries`,
     `${codexPaths.hooksJson}: the codex Stop hook entry`,
     ...(skipImperativeTimer() ? [] : [timer]),
+    ...(skipImperativeHub() ? [] : [hub]),
     paths.supervisorLink,
     codexSupervisorLink(),
     join(paths.binDir, "xx"),
@@ -477,14 +596,15 @@ export function uninstallTargets(live: boolean): string[] {
   ];
 }
 
-export function uninstallSupervisor(input: { liveTimer: boolean }): UninstallOutcome {
+export function uninstallSupervisor(input: { live: boolean }): UninstallOutcome {
   uninstallSettings();
-  const timer = uninstallCheckTimer(input.liveTimer);
+  const timer = uninstallCheckTimer(input.live);
+  const hub = uninstallHubService(input.live);
   uninstallCodexSupervisor();
   for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
     if (existsSync(f)) rmSync(f, { force: true });
   }
   const rc = shellRcPath();
   const pathLineRemoved = rc != null && removePathFromRc(rc);
-  return { timer, pathLineRemoved };
+  return { timer, hub, pathLineRemoved };
 }

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/types.ts

@@ -116,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();

package/src/main.ts

@@ -25,7 +25,8 @@ 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 { onLoginHome, timerDeactivationHint, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
+import { cmdServe } from "./cli/serve.ts";
+import { hubDeactivationHint, onLoginHome, timerDeactivationHint, uninstallSupervisor, uninstallTargets } from "./lib/install.ts";
 import { errorMessage } from "./lib/log.ts";
 import { HOME } from "./lib/paths.ts";
 import { c, emitError } from "./cli/render.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]" });
@@ -182,15 +185,17 @@ async function main(): Promise<number> {
         emitError({ message: `refused: HOME is the login home (${HOME}) - rerun with ${YES_FLAG} to remove these from the live install` });
         return 2;
       }
-      const out = uninstallSupervisor({ liveTimer: live });
+      const out = uninstallSupervisor({ live });
       const removed = [
         "supervisor wrapper",
         "settings entries",
         ...(out.timer === "removed" ? ["check timer"] : []),
+        ...(out.hub === "removed" ? ["usage hub service"] : []),
         ...(out.pathLineRemoved ? ["rc PATH line"] : []),
       ];
       console.log(`removed ${removed.join(", ")}`);
       if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${timerDeactivationHint()}`));
+      if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${hubDeactivationHint()}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
       console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; grok: grok-stores/; opencode-go: opencode-go-stores/) - remove accounts with \`xx rm\` to delete their credentials`);
       return 0;