tokenmaxxing 1.65.0 → 1.66.0

package/DESIGN.md

@@ -38,12 +38,12 @@ 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.
 
-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.
 
 ---
 

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.65.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/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/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,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]" });