tokenmaxxing 0.1.0 → 0.2.1

package/DESIGN.md

@@ -0,0 +1,125 @@
+# tokenmaxxing - design
+
+Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses **95%** usage, 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 at once.
+
+> Scope: **Claude Code only, macOS first.** Codex and other CLIs deferred (see `.memory/cc-codex-auth-mechanics.md`).
+>
+> Status: **implemented** (v0.1.0, 2026-07-09). TypeScript on Bun → single binary; Zod validates every external-boundary payload, JSON config, es-toolkit for utilities, `flock(2)` via `bun:ffi`. All load-bearing external facts were adversarially verified against the `2.1.204` binary + docs (OAuth token endpoint is `platform.claude.com/v1/oauth/token`, client_id `9d1c250a-…`, JSON body). What the acceptance gate actually shows is in §9.
+
+---
+
+## 1. Why there is a thin supervisor (and why that's the whole trick)
+
+A **running** `claude` cannot adopt a swapped credential mid-flight - binary-verified: it holds its OAuth token in memory and a 429 (the limit event) does **not** invalidate it, so it never re-reads the keychain on the event we care about. A keychain swap is only picked up by a **fresh** `claude` process.
+
+The clean way to exploit that is not to fight the live process but to **replace it at a salvageable moment**: after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt - killing it there loses nothing, and a `claude --resume <session-id>` comes back cold on the new account and continues exactly where it left off. **This is why we swap at 95%: the 5% headroom is the budget to reach a clean turn boundary and respawn before the account actually hits the wall.**
+
+A hook can't do the respawn - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
+
+```
+supervisor (you type `claude`)  →  real claude (in a PTY)  →  Stop hook
+        ▲_______________ relaunch --resume <sid> ______________|
+```
+
+It is a process/PTY manager only - spawn, forward the terminal, wait, restore terminal, relaunch. It never proxies API traffic or handles tokens. Everything else about `claude` is unchanged.
+
+---
+
+## 2. What tokenmaxxing installs
+
+- A `claude` **supervisor** on your PATH ahead of the real binary (`~/.config/tokenmaxxing/bin/claude`), or a shell function - you invoke it identically.
+- Three `~/.claude/settings.json` entries (merged, preserving anything you already have): a transparent `statusLine` shim, a `Stop` hook, a `SessionStart` hook.
+- **`~/.config/tokenmaxxing/`** - the single home for config and state:
+  - `config.json` - threshold, account order/policy.
+  - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, lastUsage, resetsAt, needs_reauth}`.
+  - `usage.json` - live usage, written by the statusLine shim.
+  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal).
+  - `bin/claude` - the supervisor.
+- Per-account **credentials** follow the platform's Claude Code store: macOS = login-keychain items `tokenmaxxing-cred-<accountUuid[:8]>` (never plaintext on disk); Linux = 0600 files `creds/tokenmaxxing-cred-<accountUuid[:8]>.json` (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.
+
+No background daemon - it's event-driven (statusline pushes usage; hooks + supervisor react). The `claude` binary and `~/.claude` layout are untouched.
+
+---
+
+## 3. How a switch happens
+
+### 3.1 Usage feed (free, push-based)
+The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine shim tees that to `usage.json` (write-on-change, O(ms)) and passes your real statusline through unchanged. Cold-start fallback if `usage.json` is absent: `TOKENMAXXING_PROBE=1 claude -p '/usage'`, with `[ -n "$TOKENMAXXING_PROBE" ] && exit 0` as the hook's first line to stop the nested process recursing (hooks fire in `-p` too). The probe scrubs every ambient credential override claude reads before the keychain (`CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, etc.) so it can only meter the credential in the keychain item, and retries the transient empty-footer case (claude prints local stats with no percentages when its own usage fetch throttles).
+
+### 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).
+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)
+The supervisor's `claude` call returns; it sees `respawn/<sid>`, deletes it, resets the terminal, prints `↻ switched to <account>`, and relaunches `claude --resume <sid>`. The resumed process reads the keychain cold → runs on the new account, same conversation. The `SessionStart` hook (source `resume`) re-checks the account before the first turn as a backstop.
+
+### 3.4 Swap sequence (under the lock)
+1. **Harvest the live credential into its TRUE owner's backup** - read the current `Claude Code-credentials` blob and resolve which account it actually belongs to via the roles endpoint (`GET /api/oauth/claude_cli/roles`), NOT the `accounts.json` active label. The label drifts from the live blob (a kill mid-swap, a manual `/login`), and harvesting by label once overwrote another account's backup and destroyed its only credential. Mandatory anyway: Claude rotates the refresh token in place, so older backups are dead. Refuse the swap if the live credential belongs to no pooled account.
+2. **Refresh B** - OAuth refresh-grant with B's parked refresh token → fresh access token; persist the rotated refresh token. On `invalid_grant`, mark B `needs_reauth`, notify, try the next account.
+3. **Install B** - `security add-generic-password -U … 'Claude Code-credentials' …` with B's fresh (non-expired) `claudeAiOauth` JSON.
+4. **Swap identity + mark B active** - atomically rewrite only the `oauthAccount` object in `~/.claude.json` (temp+rename) to B's, and write `activeAccountUuid = B` in the SAME critical section, so a crash can't leave the installed credential and the active label pointing at different accounts.
+5. Do steps 1, 3, 4 inside Claude's own `~/.claude.lock` so the writes can't collide with a token refresh.
+
+### 3.5 Multiple concurrent sessions
+Each terminal ran the supervisor, so each has its own child `claude`, its own `--session-id`, and its own respawn marker. When the shared account hits 95%, the first Stop hook to win the `flock` performs the one swap; **every** session's Stop hook writes its own respawn marker and SIGTERMs its own `claude`; **every** supervisor independently relaunches `claude --resume <its-own-sid>`. All of them come back on the new account, each continuing its own conversation. (They share one credential, so they always move together - consistent with "one current account, many windows.")
+
+---
+
+## 4. Onboarding (no `adopt`)
+
+- **`tokenmaxxing init` imports the account you're already on - automatically, no prompts, no re-login.** It reads the live `Claude Code-credentials` keychain blob plus the `oauthAccount` object in `~/.claude.json` (email, `organizationUuid`, `accountUuid`, plan tier) and writes them as **account #1** into tokenmaxxing's store (`tokenmaxxing-cred-<accountUuid[:8]>` + an `accounts.json` index entry). Nothing about your current session changes - that account stays active; it's now just also a registered pool member. After this one command you already have a working (single-account) pool. `init` also installs the supervisor + the three settings entries.
+  - If the current auth is API-key mode (`ANTHROPIC_API_KEY`/`apiKeyHelper`) rather than a subscription `/login`, there's no quota-poolable subscription credential to import - `init` says so and points you to `/login` first (per-token API billing isn't what tokenmaxxing pools).
+- **`tokenmaxxing add`** - registers *additional* accounts: logs one in via a throwaway `CLAUDE_CONFIG_DIR=~/.config/tokenmaxxing/onboard` (your primary login untouched), harvests it into the store, deletes the temp dir + its namespaced item. This is the **only** time `CLAUDE_CONFIG_DIR` is ever used.
+- Both commands exercise `security` reads/writes interactively (where a macOS keychain ACL prompt is acceptable), so the first access never happens cold inside a headless hook.
+
+---
+
+## 5. Rotation policy
+Trigger at `five_hour >= 95%` OR `seven_day >= 95%`, per org. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`95 − EMA(per-turn Δ%)`) so a single large turn can't blow past 100% before the next Stop hook.
+
+**Model-aware trigger.** Claude subscriptions also enforce a **per-model weekly cap** - the capable models (Fable, Opus) have a tighter weekly limit that binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the active model is in `policy.switchModels` we read it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session switches on the Fable cap; a Sonnet session rides the aggregate.
+
+---
+
+## 6. Honest papercuts
+- **Respawn hiccup.** At the swap turn you see `claude` restart (~1–2s) and resume. Anything you typed in the split second before respawn is lost - mitigate by respawning fast and showing a clear "switching" state; the supervisor resets terminal mode so nothing is left garbled.
+- **One cold turn.** Prompt cache is org-scoped: the first turn after resuming on B re-uploads context once (bigger on long transcripts).
+- **Single-turn overshoot.** If one turn jumps from <95% straight past the wall, that turn can end rate-limited before the Stop hook swaps; the respawn then still recovers it. Projected threshold reduces this.
+- **Shared blast radius.** All default-profile sessions share one keychain item, so a swap moves them all (each via its own respawn). The `flock` + re-check is mandatory or racing hooks burn two accounts at once.
+- **Refresh-token rotation / parked-token rot.** Step 1 re-harvest is mandatory; a parked refresh token can be invalidated by logging in elsewhere → picker must catch `invalid_grant`, mark `needs_reauth`, fall through.
+- **statusLine fragility.** The shim is the most visible surface - a bug flickers or breaks your real status line. Keep it O(ms), write-on-change.
+- **Keychain blob size & ps-safety.** The live `Claude Code-credentials` item also holds per-MCP-server OAuth state, so it can exceed `security -i`'s ~4KB interactive line buffer (verified on a real machine - a 4.3KB blob truncated). tokenmaxxing therefore stores parked backups as **`claudeAiOauth`-only** (small → always the ps-safe stdin write) and, on a swap, **merges** the fresh `claudeAiOauth` into the *current* live blob so MCP tokens survive the switch - using the argv write path (secret briefly visible in `ps` on your own machine) only for that one oversized live write.
+- **settings.json is user-owned.** Install by merge; ship `tokenmaxxing doctor` to verify the supervisor + 3 entries survive a `/config` edit or update.
+
+---
+
+## 7. Scope
+**v1:** `tokenmaxxing init` / `add` / `ls` / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; 95% swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
+
+**v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
+
+**Later:** Codex as a second pool; tool-agnostic picker.
+
+**Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap.
+
+---
+
+## 8. Stack
+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: **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.
+3. **SessionStart swap - ✅ swap logic proven; ⚠️ "adopted by first turn" needs a 2nd real account.** The hook's decision+swap path is covered by the E2E; the claude-internal timing (SessionStart before first `getToken`) needs a second subscription to observe end-to-end.
+4. **Keychain writes from a headless hook - ✅ proven.** The swap E2E's 4 concurrent subprocesses each wrote the live item via `security -i` (secret on stdin, never argv) with no prompt/hang; `init` parked backups headlessly too. (Residual: the live `Claude Code-credentials` ACL for the *fresh resumed claude* is mitigated by onboarding touching `security` interactively.)
+5. **Concurrent flocked swap - ✅ proven.** 4 concurrent processes racing the trigger → exactly **one** `flock`ed swap, one OAuth refresh, all end on B. Per-supervisor respawn is proven with the mock; N *real* supervisors respawning together needs real accounts + PTYs.
+6. **Model-aware trigger - ✅ proven.** Fable at 96% per-model cap (aggregate only 30/50) → swaps; Sonnet at 96% → no swap.
+
+Owed before fully trusting in the wild: the live interactive-PTY SIGTERM/terminal test, and the two items that require a **second real subscription account** (SessionStart adoption, N real supervisors).
+```

package/README.md

@@ -0,0 +1,88 @@
+# tokenmaxxing
+
+**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 and Linux. It pools **subscription** accounts (Pro/Max), not API keys.
+
+```
+$ claude
+  …you work normally…
+  ↻ tokenmaxxing: switched to work@acme.com - resuming…
+  …same conversation, fresh quota…
+```
+
+## Why
+
+A running `claude` holds its OAuth token in memory and a 429 does **not** make it re-read the credential store - so you can't hot-swap a live session. tokenmaxxing instead swaps the credential and **respawns** `claude --resume <id>` at a committed turn boundary (the transcript is already on disk, so nothing is lost). A thin `claude` supervisor on your PATH owns that respawn; everything else about `claude` is unchanged - all flags, MCP, hooks, and skills pass through.
+
+## Install
+
+Requires [Bun](https://bun.sh) and Claude Code, on macOS or Linux.
+
+```sh
+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:
+
+```sh
+tokenmaxxing add        # logs one in, in isolation, and pools it
+claude                  # use claude as always
+```
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `tokenmaxxing init` | import the current account + install supervisor & hooks |
+| `tokenmaxxing add` | register an additional account (isolated login, harvested into the pool) |
+| `tokenmaxxing ls` | list pooled accounts |
+| `tokenmaxxing status` | accounts with 5h / weekly usage bars, active + exhausted-until-reset |
+| `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
+| `tokenmaxxing rename <sel> <label>` · `rm <sel>` | manage the pool |
+| `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
+
+## How switching decides
+
+Switching triggers at **95%** (configurable) on any of:
+
+- **Session** (5-hour) or **week (all models)** - the aggregate windows, fed free/push-based by a statusLine shim.
+- **Per-model weekly cap** - the capable models (Fable, Opus) have their own tighter weekly limit that binds *before* the aggregate. tokenmaxxing reads it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) whenever the active model is one of `policy.switchModels`, so a Fable session switches on the Fable cap while a Sonnet session rides the aggregate.
+
+The 5% headroom is deliberate: it's the budget to reach a clean turn boundary and respawn before the wall.
+
+## Configuration
+
+`~/.config/tokenmaxxing/config.json` (every field optional):
+
+```json
+{
+  "threshold": 95,
+  "policy": {
+    "projectionMargin": 0,
+    "switchModels": ["fable", "opus"],
+    "usagePollTtlMs": 90000
+  }
+}
+```
+
+`projectionMargin` subtracts an EMA of per-turn Δ% for pre-emption; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh.
+
+State lives entirely in `~/.config/tokenmaxxing/`. Per-account credentials follow the platform's Claude Code store: the login keychain on macOS (`tokenmaxxing-cred-<uuid8>` items, never plaintext on disk), 0600 files under `~/.config/tokenmaxxing/creds/` on Linux (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
+
+## Honest limitations
+
+- **One cold turn.** The first turn after resuming on a new account re-uploads context once (prompt cache is org-scoped).
+- **Respawn hiccup.** At the swap you see `claude` restart (~1–2s); anything typed in that split second is lost.
+- **Shared blast radius.** All default-profile sessions share one live credential, so a swap moves them all together (each respawns its own session). A `flock` + re-check keeps racing hooks from burning two accounts.
+- **Keychain ACL (macOS).** `init`/`add` touch the keychain interactively so the first `security` access isn't cold inside a headless hook.
+- **Plaintext credentials (Linux).** Claude Code itself stores Linux credentials as a 0600 plaintext file; tokenmaxxing's parked copies follow the same model.
+
+## How it's built
+
+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
+
+MIT

package/package.json

@@ -1,19 +1,40 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.1.0",
-  "description": "tokenmaxxing CLI",
+  "version": "0.2.1",
+  "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",
+  "homepage": "https://github.com/anaclumos/tokenmaxxing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anaclumos/tokenmaxxing.git"
+  },
   "bin": {
-    "tokenmaxxing": "./dist/index.js"
+    "tokenmaxxing": "./src/main.ts"
   },
   "files": [
-    "dist"
+    "src",
+    "README.md",
+    "DESIGN.md"
   ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "os": ["darwin", "linux"],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target node",
-    "dev": "bun run ./src/index.ts"
+    "dev": "bun run src/main.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun run test"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "es-toolkit": "^1.49.0",
+    "ky": "^2.0.2",
+    "zod": "^4.4.3"
   }
 }

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;
+}