tokenmaxxing 0.2.0 → 0.3.0

package/DESIGN.md

@@ -48,7 +48,7 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
 1. Read `usage.json`; `exit 0` fast if both windows `< 95%` (metered per `organizationUuid`).
-2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (lowest 7-day, not rate-limited, soonest `resets_at` tiebreak), and **swap the credential** (§3.4).
+2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (not rate-limited, soonest-expiring weekly window first since unused allowance is forfeited at the fixed per-account reset, lowest 7-day usage tiebreak), and **swap the credential** (§3.4).
 3. Write `respawn/<session_id>` (atomic temp+rename) and `SIGTERM` the parent `claude` (`kill -TERM $PPID`). The turn is already committed, so this is a clean stop.
 
 ### 3.3 Respawn (supervisor)
@@ -106,13 +106,13 @@ Trigger at `five_hour >= 95%` OR `seven_day >= 95%`, per org. "Exhausted" is a *
 ---
 
 ## 8. Stack
-TypeScript on Bun, `bun build --compile` → the `claude` supervisor, the statusLine shim, and the hook as fast-starting single binaries (the Stop path runs every turn, so start-up latency matters). npm name `tokenmaxxing` owned. The supervisor needs a real PTY layer (spawn claude on a pty, forward resize/signals, restore mode between runs).
+TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` supervisor, the statusLine shim, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry (the Stop path runs every turn; bun's start-up stays low-millisecond). Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). The supervisor needs a real PTY layer (spawn claude on a pty, forward resize/signals, restore mode between runs).
 
 ---
 
 ## 9. What the acceptance gate showed (2026-07-09)
 
-Unit suite: **32 pass**. Hermetic swap+concurrency+model-aware E2E: **all pass**. CLI init/doctor/uninstall through the compiled binary: **pass**.
+Unit suite: **32 pass**. Hermetic swap+concurrency+model-aware E2E: **all pass**. CLI init/doctor/uninstall: **pass** (re-verified init/doctor 2026-07-09 through the npm-installed bun shim on linux-arm64 after the switch to source packaging; full suite 47 pass / 0 fail there).
 
 1. **Transcript continuity across a process boundary - ✅ proven on real claude/real account.** `claude --session-id X -p …` committed a clean 12-line transcript; `claude --resume X -p …` recalled the earlier turn's codeword. The supervisor's kill→restore-termios→respawn→`--resume` loop is proven with a mock claude. The one step not run live is the abrupt SIGTERM of an *idle interactive* real claude (structurally safe - the transcript is fully committed+fsynced before idle and nothing writes while idle).
 2. **Terminal restoration - ✅ mechanism proven.** The supervisor saves `stty -g` and restores it between kill and respawn; the path executes in the mock-supervisor run. Visual raw-mode/​resize confirmation wants a live interactive terminal.

package/README.md

@@ -2,7 +2,7 @@
 
 **Automatic Claude Code account switching.** Run `claude` exactly as you always do; when the active account crosses its usage limit, tokenmaxxing swaps to a fresh account and - at the next safe turn boundary - restarts your session *resumed on it*, automatically. Works across many concurrent sessions.
 
-> **Scope:** Claude Code only, macOS (Apple Silicon) and Linux (x64/arm64). It pools **subscription** accounts (Pro/Max), not API keys.
+> **Scope:** Claude Code only, macOS and Linux. It pools **subscription** accounts (Pro/Max), not API keys.
 
 ```
 $ claude
@@ -20,10 +20,8 @@ A running `claude` holds its OAuth token in memory and a 429 does **not** make i
 Requires [Bun](https://bun.sh) and Claude Code, on macOS or Linux.
 
 ```sh
-git clone https://github.com/anaclumos/tokenmaxxing && cd tokenmaxxing
-bun install
-bun run build            # → dist/tokenmaxxing (single binary)
-./dist/tokenmaxxing init
+bun add -g tokenmaxxing
+tokenmaxxing init
 ```
 
 `init` imports the account you're already on, installs the `claude` supervisor + three `settings.json` entries (a statusLine shim, a Stop hook, a SessionStart hook), 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:
@@ -83,7 +81,7 @@ State lives entirely in `~/.config/tokenmaxxing/`. Per-account credentials follo
 
 ## How it's built
 
-TypeScript on Bun, compiled to a single binary with `bun build --compile`. [Zod](https://zod.dev) validates every external-boundary payload (credential blobs, hook/statusLine stdin, OAuth responses, config), [es-toolkit](https://es-toolkit.dev) for utilities. The supervisor is process/terminal-only - it never proxies API traffic or touches tokens in flight. Cross-process coordination uses `flock(2)` via `bun:ffi` (macOS has no `flock(1)`; one codepath serves both platforms). Credential I/O goes through one platform-selected store: `security(1)` generic-passwords on macOS, atomic 0600 file writes on Linux.
+TypeScript on Bun: one multi-call entry (`src/main.ts`) serves the CLI, the `claude` supervisor, and the hook/statusLine shims, and runs directly under bun. [Zod](https://zod.dev) validates every external-boundary payload (credential blobs, hook/statusLine stdin, OAuth responses, config), [es-toolkit](https://es-toolkit.dev) for utilities. The supervisor is process/terminal-only - it never proxies API traffic or touches tokens in flight. Cross-process coordination uses `flock(2)` via `bun:ffi` (macOS has no `flock(1)`; one codepath serves both platforms). Credential I/O goes through one platform-selected store: `security(1)` generic-passwords on macOS, atomic 0600 file writes on Linux.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.2.0",
-  "description": "Automatic Claude Code account switching — pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
+  "version": "0.3.0",
+  "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",
   "author": "anaclumos",
@@ -11,10 +11,10 @@
     "url": "git+https://github.com/anaclumos/tokenmaxxing.git"
   },
   "bin": {
-    "tokenmaxxing": "./dist/tokenmaxxing"
+    "tokenmaxxing": "./src/main.ts"
   },
   "files": [
-    "dist/tokenmaxxing",
+    "src",
     "README.md",
     "DESIGN.md"
   ],
@@ -22,16 +22,11 @@
     "bun": ">=1.1.0"
   },
   "os": ["darwin", "linux"],
-  "cpu": ["arm64", "x64"],
   "scripts": {
     "dev": "bun run src/main.ts",
-    "build": "bun build --compile --minify --sourcemap src/main.ts --outfile dist/tokenmaxxing",
-    "build:dev": "bun build --compile src/main.ts --outfile dist/tokenmaxxing",
-    "build:linux-x64": "bun build --compile --minify --sourcemap --target=bun-linux-x64 src/main.ts --outfile dist/tokenmaxxing-linux-x64",
-    "build:linux-arm64": "bun build --compile --minify --sourcemap --target=bun-linux-arm64 src/main.ts --outfile dist/tokenmaxxing-linux-arm64",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run typecheck && bun run test && bun run build"
+    "prepublishOnly": "bun run typecheck && bun run test"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cli/add.ts

@@ -0,0 +1,129 @@
+// `tokenmaxxing add` - register an ADDITIONAL account. Logs one in inside a
+// throwaway CLAUDE_CONFIG_DIR (the ONLY use of CLAUDE_CONFIG_DIR), auto-exits the
+// moment the login lands, samples that account's usage, then harvests its
+// credential + identity into the pool and deletes the temp dir + isolated
+// credential. Your primary login is never touched.
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { readItem, writeItem, deleteItem, parkedTarget, isolatedTarget, claudeAiOauthOnly } from "../lib/credstore.ts";
+import { resolveRealClaude } from "../lib/claudebin.ts";
+import { probeUsage } from "../lib/usage.ts";
+import { saveTermios, restoreTermios } from "../lib/tty.ts";
+import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { credItemFor, paths } from "../lib/paths.ts";
+import { CredentialBlobSchema, OAuthAccountSchema, type Account } from "../lib/types.ts";
+import { c } from "./render.ts";
+
+/** True once `/login` has written a usable identity into the onboard dir. */
+function identityReady(cjPath: string): boolean {
+  if (!existsSync(cjPath)) return false;
+  try {
+    const oauthAccount = JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount;
+    return z.object({ accountUuid: z.string().min(1) }).safeParse(oauthAccount).success;
+  } catch {
+    return false;
+  }
+}
+
+export async function cmdAdd(): Promise<number> {
+  const onboardDir = paths.onboardDir;
+  rmSync(onboardDir, { recursive: true, force: true });
+  mkdirSync(onboardDir, { recursive: true });
+  const iso = isolatedTarget(onboardDir);
+  const cjPath = join(onboardDir, ".claude.json");
+  const real = resolveRealClaude();
+
+  console.log(c.cyan("Opening an isolated Claude login - your primary login is untouched."));
+  console.log(c.dim(`In the session that opens, run  ${c.bold("/login")}  with the account to add. It closes itself once you're in.`));
+  console.log();
+
+  const savedTermios = saveTermios();
+  // Scrub the ambient credential/identity overrides claude honors BEFORE its
+  // keychain lookup (verified 2.1.205) - the onboard session must authenticate
+  // only via the /login the user performs inside it.
+  const env: Record<string, string> = { ...process.env, CLAUDE_CONFIG_DIR: onboardDir, TOKENMAXXING_PROBE: "1", TOKENMAXXING_SUPERVISED: "" };
+  delete env.ANTHROPIC_API_KEY;
+  delete env.ANTHROPIC_AUTH_TOKEN;
+  delete env.CLAUDE_CODE_OAUTH_TOKEN;
+  delete env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
+  const p = Bun.spawn([real], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env,
+  });
+
+  // Auto-exit (#17): watch for a completed login - identity written AND the
+  // isolated credential present - then SIGTERM claude. No manual /exit.
+  let exited = false;
+  const onExit = p.exited.then(() => { exited = true; });
+  while (!exited) {
+    await Bun.sleep(400);
+    if (identityReady(cjPath) && (await readItem(iso))) {
+      p.kill();
+      break;
+    }
+  }
+  await p.exited;
+  await onExit;
+  restoreTermios(savedTermios);
+
+  const cleanup = async () => {
+    await deleteItem(iso);
+    rmSync(onboardDir, { recursive: true, force: true });
+  };
+
+  const blobRaw = await readItem(iso);
+  if (!blobRaw || !identityReady(cjPath)) {
+    console.error(c.red("no login detected in the isolated session - nothing added."));
+    await cleanup();
+    return 1;
+  }
+
+  let blob, oauthAccount;
+  try {
+    blob = CredentialBlobSchema.parse(JSON.parse(blobRaw));
+    oauthAccount = OAuthAccountSchema.parse(JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount);
+  } catch {
+    console.error(c.red("could not parse the onboarded account's credential/identity."));
+    await cleanup();
+    return 1;
+  }
+
+  // Sample usage now (#16) so the account isn't "not sampled yet" in status/ls.
+  console.log(c.dim("sampling usage…"));
+  const sampled = await probeUsage(onboardDir);
+  if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+
+  const uuid = oauthAccount.accountUuid;
+  const keychainItem = credItemFor(uuid);
+  await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw)); // park a small backup
+
+  const idx = loadAccounts();
+  const existing = idx.accounts.find((a) => a.accountUuid === uuid);
+  const account: Account = {
+    accountUuid: uuid,
+    email: oauthAccount.emailAddress,
+    organizationUuid: oauthAccount.organizationUuid,
+    label: existing?.label ?? oauthAccount.emailAddress,
+    keychainItem,
+    oauthAccount,
+    addedAt: existing?.addedAt ?? new Date().toISOString(),
+    subscriptionType: blob.claudeAiOauth.subscriptionType,
+    needsReauth: false,
+    lastUsage: sampled ? { fiveHour: sampled.session, sevenDay: sampled.weekAll } : existing?.lastUsage,
+    lastPerModel: sampled && Object.keys(sampled.perModel).length > 0 ? sampled.perModel : existing?.lastPerModel,
+  };
+  if (existing) Object.assign(existing, account);
+  else idx.accounts.push(account);
+  saveAccounts(idx);
+
+  await cleanup();
+
+  console.log();
+  const usageNote = sampled ? ` · session ${sampled.session.usedPercentage}% / week ${sampled.weekAll.usedPercentage}%` : "";
+  console.log(`${c.green("✓")} added ${c.bold(account.email)} (${account.subscriptionType ?? "?"})${usageNote} → pool now has ${idx.accounts.length} account(s)`);
+  return 0;
+}

package/src/cli/doctor.ts

@@ -0,0 +1,80 @@
+// `tokenmaxxing doctor` - verify the supervisor + three settings entries survived
+// and the pool is healthy.
+
+import { existsSync } from "node:fs";
+import { checkSettings, installedBin } from "../lib/settings.ts";
+import { isBinDirAhead } from "../lib/install.ts";
+import { paths } from "../lib/paths.ts";
+import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { readItem, liveTarget, parkedTarget } from "../lib/credstore.ts";
+import { isAccessTokenExpiring, fetchTokenOrg } from "../lib/oauth.ts";
+import { CredentialBlobSchema, type RolesResponse } from "../lib/types.ts";
+import { c } from "./render.ts";
+
+/** The org a stored blob's token truly belongs to; null = expired (unverifiable
+ *  read-only - doctor never refreshes). Throws on unreadable blob / API failure. */
+async function blobOrg(raw: string): Promise<RolesResponse | null> {
+  const creds = CredentialBlobSchema.parse(JSON.parse(raw)).claudeAiOauth;
+  if (isAccessTokenExpiring(creds)) return null;
+  return fetchTokenOrg(creds.accessToken);
+}
+
+export async function cmdDoctor(): Promise<number> {
+  let ok = true;
+  const check = (cond: boolean, label: string, hint?: string) => {
+    console.log(`${cond ? c.green("✓") : c.red("✗")} ${label}${!cond && hint ? c.dim(`  - ${hint}`) : ""}`);
+    if (!cond) ok = false;
+  };
+
+  check(existsSync(paths.supervisorLink), "claude supervisor wrapper present", "run `tokenmaxxing init`");
+  check(existsSync(installedBin()), "tokenmaxxing binary installed", "run `tokenmaxxing init`");
+  check(isBinDirAhead(), `${paths.binDir} is ahead of the real claude on PATH`, `export PATH="${paths.binDir}:$PATH"`);
+
+  const s = checkSettings();
+  check(s.statusLineOk, "statusLine shim installed in settings.json", "run `tokenmaxxing init`");
+  check(s.stopOk, "Stop hook installed in settings.json", "run `tokenmaxxing init`");
+  check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
+
+  const idx = loadAccounts();
+  check(idx.accounts.length > 0, "at least one account in the pool", "run `tokenmaxxing init`");
+  check(!!idx.activeAccountUuid, "an active account is set");
+
+  const live = await readItem(liveTarget());
+  check(!!live, "live credential readable");
+
+  // Identity agreement: a stored credential must belong to the account it is
+  // filed under - a mislabeled blob once made every consumer of a backup
+  // (sampling, swap) silently act on another account.
+  const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid);
+  if (live && active) {
+    try {
+      const org = await blobOrg(live);
+      if (org) check(org.organization_uuid === active.organizationUuid, `live credential identity matches active (${active.email})`, `token belongs to ${org.organization_name} - run \`tokenmaxxing switch\``);
+      else console.log(c.dim(`  · live credential identity unverifiable (access token expired)`));
+    } catch (e) {
+      check(false, `live credential identity matches active (${active.email})`, String((e as Error).message ?? e).slice(0, 100));
+    }
+  }
+
+  for (const a of idx.accounts) {
+    const parked = await readItem(parkedTarget(a.keychainItem));
+    check(!!parked, `parked credential present for ${a.email}`, "re-run `tokenmaxxing init`/`add`");
+    if (parked) {
+      try {
+        const org = await blobOrg(parked);
+        if (org) check(org.organization_uuid === a.organizationUuid, `parked credential identity matches ${a.email}`, `token belongs to ${org.organization_name} - re-auth with \`tokenmaxxing add\``);
+        else console.log(c.dim(`  · ${a.email} identity unverifiable (access token expired)`));
+      } catch (e) {
+        check(false, `parked credential identity matches ${a.email}`, String((e as Error).message ?? e).slice(0, 100));
+      }
+    }
+    if (a.needsReauth) check(false, `${a.email} needs re-auth`, "run `tokenmaxxing add` to re-login");
+  }
+
+  const cfg = loadConfig();
+  check(!!cfg.claudeBin && existsSync(cfg.claudeBin), "real claude binary resolved", "set claudeBin in config.json");
+
+  console.log();
+  console.log(ok ? c.green("all good ✓") : c.yellow("issues found - see above"));
+  return ok ? 0 : 1;
+}

package/src/cli/init.ts

@@ -0,0 +1,124 @@
+// `tokenmaxxing init` - import the account you're already on (no prompts), then
+// install the supervisor + the three settings entries.
+
+import { mkdirSync } from "node:fs";
+import { isApiKeyMode, readOAuthAccount } from "../lib/claudejson.ts";
+import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "../lib/credstore.ts";
+import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg } from "../lib/oauth.ts";
+import { loadAccounts, saveAccounts, loadConfig, saveConfig } from "../lib/state.ts";
+import { installSupervisor, shellRcPath, ensurePathInRc } from "../lib/install.ts";
+import { resolveRealClaude } from "../lib/claudebin.ts";
+import { credItemFor, paths } from "../lib/paths.ts";
+import { CredentialBlobSchema, type Account } from "../lib/types.ts";
+import { c } from "./render.ts";
+
+/** Put the supervisor bin dir on PATH via the user's shell rc (idempotent).
+ *  Falls back to the manual instruction when the shell is unknown. */
+function ensurePathAhead(): void {
+  const rc = shellRcPath();
+  if (!rc) {
+    console.log(c.yellow(`⚠ add to your shell rc: export PATH="${paths.binDir}:$PATH"`));
+    return;
+  }
+  const outcome = ensurePathInRc(rc);
+  if (outcome === "added") console.log(`${c.green("✓")} added ${paths.binDir} to PATH in ${rc} - restart your shell (or \`source ${rc}\`)`);
+  else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
+}
+
+export async function cmdInit(): Promise<number> {
+  mkdirSync(paths.home, { recursive: true });
+
+  // Already initialized → repair install ONLY. Never re-import: ~/.claude.json's
+  // oauthAccount can drift from the live keychain cred (after swaps / concurrent
+  // sessions), and re-importing would park the wrong cred + mislabel active.
+  const existingIdx = loadAccounts();
+  if (existingIdx.accounts.length > 0) {
+    const out = installSupervisor();
+    // repair the claudeBin pin too - hooks run with claude's PATH and must
+    // never have to guess which binary is the real claude.
+    const cfg = loadConfig();
+    cfg.claudeBin = resolveRealClaude();
+    saveConfig(cfg);
+    const active = existingIdx.accounts.find((a) => a.accountUuid === existingIdx.activeAccountUuid);
+    console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
+    if (!out.pathAhead) ensurePathAhead();
+    console.log(`  active: ${c.bold(active?.label ?? "unknown")} · run ${c.cyan("tokenmaxxing add")} for more, ${c.cyan("tokenmaxxing status")} to check`);
+    return 0;
+  }
+
+  if (isApiKeyMode()) {
+    console.error(c.yellow("tokenmaxxing pools subscription accounts, but you're authed via API key / apiKeyHelper."));
+    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} with a Pro/Max account first, then re-run ${c.cyan("tokenmaxxing init")}.`);
+    return 1;
+  }
+
+  const oauthAccount = readOAuthAccount();
+  const liveRaw = await readItem(liveTarget());
+  if (!oauthAccount || !liveRaw) {
+    console.error(c.red("no active Claude subscription login found (missing oauthAccount or credential)."));
+    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} first, then re-run ${c.cyan("tokenmaxxing init")}.`);
+    return 1;
+  }
+
+  let blob;
+  try {
+    blob = CredentialBlobSchema.parse(JSON.parse(liveRaw));
+  } catch {
+    console.error(c.red("the live credential is not a recognizable Claude OAuth blob."));
+    return 1;
+  }
+
+  // Verify the live credential actually belongs to the identity we're about to
+  // file it under - ~/.claude.json's oauthAccount can drift from the live
+  // keychain credential, and importing on drifted state parks a mislabeled blob.
+  let creds = blob.claudeAiOauth;
+  if (isAccessTokenExpiring(creds)) {
+    creds = await refreshCredential(creds);
+    await writeItem(liveTarget(), mergeIntoLive(liveRaw, creds));
+  }
+  const org = await fetchTokenOrg(creds.accessToken);
+  if (org.organization_uuid !== oauthAccount.organizationUuid) {
+    console.error(c.red(`the live credential belongs to ${org.organization_name}, but ~/.claude.json identifies ${oauthAccount.emailAddress} - identity drift.`));
+    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} to realign them, then re-run ${c.cyan("tokenmaxxing init")}.`);
+    return 1;
+  }
+
+  const uuid = oauthAccount.accountUuid;
+  const keychainItem = credItemFor(uuid);
+  await writeItem(parkedTarget(keychainItem), JSON.stringify({ claudeAiOauth: creds })); // park a small backup
+
+  const idx = loadAccounts();
+  const existing = idx.accounts.find((a) => a.accountUuid === uuid);
+  const account: Account = {
+    accountUuid: uuid,
+    email: oauthAccount.emailAddress,
+    organizationUuid: oauthAccount.organizationUuid,
+    label: existing?.label ?? oauthAccount.emailAddress,
+    keychainItem,
+    oauthAccount,
+    addedAt: existing?.addedAt ?? new Date().toISOString(),
+    subscriptionType: blob.claudeAiOauth.subscriptionType,
+    needsReauth: false,
+  };
+  if (existing) Object.assign(existing, account);
+  else idx.accounts.push(account);
+  idx.activeAccountUuid = uuid;
+  saveAccounts(idx);
+
+  const cfg = loadConfig();
+  cfg.claudeBin = resolveRealClaude();
+  saveConfig(cfg);
+
+  const out = installSupervisor();
+
+  console.log(`${c.green("✓")} imported current account → ${c.bold(account.email)} (${account.subscriptionType ?? "?"})`);
+  console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/SessionStart hooks`);
+  if (out.priorStatusLine) console.log(`${c.green("✓")} wrapped your existing statusLine (preserved)`);
+  if (!out.pathAhead) {
+    console.log();
+    ensurePathAhead();
+  }
+  console.log();
+  console.log(`  pool ready (${idx.accounts.length} account${idx.accounts.length === 1 ? "" : "s"}) · add more with ${c.cyan("tokenmaxxing add")}`);
+  return 0;
+}

package/src/cli/ls.ts

@@ -0,0 +1,24 @@
+// `tokenmaxxing ls` - compact list of pooled accounts.
+
+import { loadAccounts } from "../lib/state.ts";
+import { c } from "./render.ts";
+
+export function cmdLs(): number {
+  const idx = loadAccounts();
+  if (idx.accounts.length === 0) {
+    console.log(c.dim("no accounts yet - run `tokenmaxxing init` then `tokenmaxxing add`"));
+    return 0;
+  }
+  for (const a of idx.accounts) {
+    const active = a.accountUuid === idx.activeAccountUuid;
+    const marker = active ? c.green("●") : c.dim("○");
+    const flags: string[] = [];
+    if (active) flags.push(c.green("active"));
+    if (a.needsReauth) flags.push(c.red("needs-reauth"));
+    const tag = flags.length ? ` ${flags.join(" ")}` : "";
+    const label = a.label || a.email;
+    console.log(`${marker} ${c.bold(label)}${tag}`);
+    console.log(`  ${c.dim(`org ${a.organizationUuid.slice(0, 8)} · ${a.subscriptionType ?? "?"} · uuid ${a.accountUuid.slice(0, 8)}`)}`);
+  }
+  return 0;
+}

package/src/cli/rename.ts

@@ -0,0 +1,33 @@
+// `tokenmaxxing rename <selector> <new-label>` - relabel a pooled account.
+
+import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { c } from "./render.ts";
+import type { Account } from "../lib/types.ts";
+
+/** Resolve an account by email, label, or accountUuid prefix. */
+export function findAccount(accounts: Account[], selector: string): Account | undefined {
+  const s = selector.toLowerCase();
+  return (
+    accounts.find((a) => a.email.toLowerCase() === s) ??
+    accounts.find((a) => a.label.toLowerCase() === s) ??
+    accounts.find((a) => a.accountUuid.toLowerCase().startsWith(s))
+  );
+}
+
+export function cmdRename(selector?: string, newLabel?: string): number {
+  if (!selector || !newLabel) {
+    console.error("usage: tokenmaxxing rename <email|label|uuid> <new-label>");
+    return 2;
+  }
+  const idx = loadAccounts();
+  const a = findAccount(idx.accounts, selector);
+  if (!a) {
+    console.error(c.red(`no account matches "${selector}"`));
+    return 1;
+  }
+  const old = a.label;
+  a.label = newLabel;
+  saveAccounts(idx);
+  console.log(`renamed ${c.dim(old)} → ${c.bold(newLabel)}`);
+  return 0;
+}

package/src/cli/render.ts

@@ -0,0 +1,36 @@
+// Terminal rendering helpers for the CLI (bars, colors, relative times).
+
+import { clamp } from "es-toolkit";
+
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY;
+
+export const c = {
+  dim: (s: string) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s: string) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+  green: (s: string) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  yellow: (s: string) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+  red: (s: string) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+  cyan: (s: string) => (useColor ? `\x1b[36m${s}\x1b[0m` : s),
+};
+
+/** A fixed-width usage bar, colored by fill. */
+export function bar(pct: number, width = 16): string {
+  const clamped = clamp(pct, 0, 100);
+  const filled = Math.round((clamped / 100) * width);
+  const body = "█".repeat(filled) + "░".repeat(width - filled);
+  const label = `${clamped.toFixed(0).padStart(3)}%`;
+  const paint = clamped >= 95 ? c.red : clamped >= 75 ? c.yellow : c.green;
+  return `${paint(body)} ${label}`;
+}
+
+/** Relative-time string for a reset epoch, e.g. "resets in 2h13m". */
+export function fmtReset(epochMs: number | null | undefined, now = Date.now()): string {
+  if (epochMs == null) return "";
+  const dsec = Math.round((epochMs - now) / 1000);
+  if (dsec <= 0) return "reset now";
+  const h = Math.floor(dsec / 3600);
+  const m = Math.floor((dsec % 3600) / 60);
+  if (h > 24) return `resets in ${Math.floor(h / 24)}d${h % 24}h`;
+  if (h > 0) return `resets in ${h}h${m}m`;
+  return `resets in ${m}m`;
+}

package/src/cli/rm.ts

@@ -0,0 +1,28 @@
+// `tokenmaxxing rm <selector>` - remove a pooled account (not the active one).
+
+import { deleteItem, parkedTarget } from "../lib/credstore.ts";
+import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { findAccount } from "./rename.ts";
+import { c } from "./render.ts";
+
+export async function cmdRm(selector?: string): Promise<number> {
+  if (!selector) {
+    console.error("usage: tokenmaxxing rm <email|label|uuid>");
+    return 2;
+  }
+  const idx = loadAccounts();
+  const a = findAccount(idx.accounts, selector);
+  if (!a) {
+    console.error(c.red(`no account matches "${selector}"`));
+    return 1;
+  }
+  if (a.accountUuid === idx.activeAccountUuid) {
+    console.error(c.red(`${a.email} is the ACTIVE account - switch away before removing it.`));
+    return 1;
+  }
+  await deleteItem(parkedTarget(a.keychainItem));
+  idx.accounts = idx.accounts.filter((x) => x.accountUuid !== a.accountUuid);
+  saveAccounts(idx);
+  console.log(`removed ${c.bold(a.label)} from the pool (${idx.accounts.length} left)`);
+  return 0;
+}

package/src/cli/status.ts

@@ -0,0 +1,99 @@
+// `tokenmaxxing status`: accounts with 5h / weekly / per-model usage bars.
+// Parked accounts are live-sampled in isolation (`claude -p /usage`); the active
+// account is read off the free statusLine feed (usage.json) so we never poll its
+// own busy token. A sample that fails falls back to the last-known values with a
+// visible "(cached)" note - never a silent stale number. Fresh figures are
+// persisted onto each account for the picker/switch logic.
+
+import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts } from "../lib/state.ts";
+import { readOAuthAccount } from "../lib/claudejson.ts";
+import { probeActiveUsage, probeParkedUsage, type SampleOutcome } from "../lib/sample.ts";
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
+import { isExhausted } from "../lib/picker.ts";
+import { bar, c, fmtReset } from "./render.ts";
+import type { FullUsage } from "../lib/usage.ts";
+import type { UsageWindow } from "../lib/types.ts";
+
+export async function cmdStatus(): Promise<number> {
+  const idx = loadAccounts();
+  const cfg = loadConfig();
+  const live = loadUsage();
+  const modelUsage = loadModelUsage();
+  const now = Date.now();
+
+  if (idx.accounts.length === 0) {
+    console.log(c.dim("no accounts yet, run `tokenmaxxing init`"));
+    return 0;
+  }
+
+  const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+
+  // Sample under the flock so parked refreshes can't collide with an in-flight swap.
+  console.error(c.dim("sampling live usage…"));
+  const outcomes = new Map<string, SampleOutcome>();
+  await withLock(paths.lockFile, () =>
+    Promise.all(
+      idx.accounts.map(async (a) => {
+        const isActive = a.accountUuid === idx.activeAccountUuid && activeOrg === a.organizationUuid;
+        // Active account: prefer the free statusLine push (usage.json) so we never
+        // poll its own token, which is busy exactly when it matters. per-model
+        // comes from model-usage.json (also statusLine-driven).
+        const fromStatusLine: FullUsage | null =
+          isActive && live && live.org === a.organizationUuid
+            ? {
+                session: live.fiveHour,
+                weekAll: live.sevenDay,
+                perModel: modelUsage && modelUsage.org === a.organizationUuid ? modelUsage.perModel : {},
+              }
+            : null;
+        const outcome: SampleOutcome = fromStatusLine
+          ? { ok: true, usage: fromStatusLine }
+          : isActive
+            ? await probeActiveUsage(a)
+            : await probeParkedUsage(a);
+        outcomes.set(a.accountUuid, outcome);
+        if (!outcome.ok) return;
+        a.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
+        if (Object.keys(outcome.usage.perModel).length > 0) a.lastPerModel = outcome.usage.perModel;
+      }),
+    ),
+  );
+  saveAccounts(idx);
+
+  console.log(c.dim(`threshold ${cfg.threshold}%  ·  ${idx.accounts.length} account(s)`));
+  console.log();
+
+  const row = (name: string, w: UsageWindow) =>
+    console.log(`    ${name.padEnd(5)} ${bar(w.usedPercentage)}  ${c.dim(fmtReset(w.resetsAt, now))}`);
+
+  for (const a of idx.accounts) {
+    const active = a.accountUuid === idx.activeAccountUuid;
+    const outcome = outcomes.get(a.accountUuid);
+    const failed = outcome ? !outcome.ok : false;
+    // On a failed sample, fall back to the last-known values (with a note below).
+    const usage = outcome?.ok ? outcome.usage : undefined;
+    const aggregate = usage ? { fiveHour: usage.session, sevenDay: usage.weekAll } : a.lastUsage;
+    const perModel = usage ? usage.perModel : a.lastPerModel;
+
+    const marker = active ? c.green("●") : c.dim("○");
+    const badges: string[] = [];
+    if (active) badges.push(c.green("active"));
+    if (a.needsReauth) badges.push(c.red("needs-reauth"));
+    if (isExhausted(a, { now, threshold: cfg.threshold, currentAccountUuid: idx.activeAccountUuid }))
+      badges.push(c.yellow("exhausted"));
+
+    console.log(`${marker} ${c.bold(a.label || a.email)} ${badges.join(" ")}`);
+    if (aggregate) {
+      row("5h", aggregate.fiveHour);
+      row("week", aggregate.sevenDay);
+    }
+    if (perModel) for (const [name, w] of Object.entries(perModel)) row(name, w);
+    if (failed && outcome && !outcome.ok) {
+      const note = aggregate || perModel ? "cached · live sample failed" : "live sample failed";
+      console.log(`    ${c.yellow(note)}: ${c.dim(outcome.reason)}`);
+    }
+    console.log();
+  }
+  return 0;
+}