tokenmaxxing 0.10.0 → 0.12.0

package/DESIGN.md

@@ -99,6 +99,8 @@ The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from the
 
 **v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
 
+**Shipped since (0.11.0):** a programmatic SDK surface (`src/sdk.ts`, the package's `exports["."]`) for pairing with the Claude Agent SDK - personal use across the owner's own pooled accounts. The Agent SDK reads credentials per subprocess spawn and has no statusLine, so the surface is boundary-driven: run the shared switch decision before a spawn (`ensureBestAccount`) and at Stop-hook turn boundaries (`stopHookCheck`), and hand the SDK a pinned real-claude path plus a full replacement env scrubbed of credential overrides (`pooledOptions`).
+
 **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.

package/README.md

@@ -40,6 +40,7 @@ claude                  # use claude as always
 | `tokenmaxxing ls` | list pooled accounts |
 | `tokenmaxxing status` | accounts with 5h / weekly usage bars, active + exhausted-until-reset |
 | `tokenmaxxing status --force` | additionally ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh |
+| `tokenmaxxing watch [seconds]` | live status: re-render every N seconds (default 120, floor 30; never pings) |
 | `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) |
@@ -75,6 +76,31 @@ The **target** is chosen greedily off each account's cached windows: among usabl
 
 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`).
 
+## Pairing with the Claude Agent SDK
+
+For agents you build on the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) against **your own** pooled accounts, `tokenmaxxing` is importable as a library (your agent app must run under Bun: tokenmaxxing ships TypeScript source and uses `bun:ffi`):
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { ensureBestAccount, pooledOptions, stopHookCheck } from "tokenmaxxing";
+
+await ensureBestAccount(); // run the switch decision before the spawn (swaps once it engages - see below)
+
+for await (const message of query({
+  prompt: "...",
+  options: {
+    ...pooledOptions(), // pinned real claude + scrubbed env -> the pooled live credential
+    hooks: { Stop: [{ hooks: [stopHookCheck] }] }, // re-decide at every turn boundary
+  },
+})) {
+  // capture the session id from the init message if you want `resume` across swaps
+}
+```
+
+The SDK reads credentials when it spawns the claude subprocess and has no statusLine, so none of the CLI-side supervisor machinery applies; the integration is boundary-driven instead. `ensureBestAccount()` runs the exact greedy decision the CLI hooks and timer run (screening bars, pace-pressure target, post-swap cooldown - all shared code); like them, it deliberately does nothing until the decision engages (the active session past `policy.greedySessionFloor`, or a bar crossed), so a fresh account rides instead of churning. `pooledOptions()` pins `pathToClaudeCodeExecutable` to the real claude binary and supplies a full replacement `env` with every ambient credential override (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, ...) scrubbed, so the subprocess resolves the pool's live credential and nothing else. The pooled surface requires the default Claude Code credential store: it fails fast if `CLAUDE_CONFIG_DIR` or `CLAUDE_SECURESTORAGE_CONFIG_DIR` is set in your app's environment, because a swap would write the live credential where those point while the spawned subprocess reads the default store. `stopHookCheck` re-runs the decision at turn boundaries; a swap it lands takes effect on the next subprocess spawn (it never yanks a mid-query token). If your app loads user settings (see the SDK's `settingSources`), the Stop hook `tokenmaxxing init` installed may already fire in SDK sessions too - `stopHookCheck` makes the check explicit and works when settings are restricted.
+
+This is for pooling **your own** subscription accounts in agents you run yourself - the same personal-use posture as the CLI. Anthropic does not allow third-party products to offer claude.ai login or rate limits, including agents built on the Agent SDK; don't ship this surface to third parties.
+
 ## Honest limitations
 
 - **One cold turn.** The first turn after resuming on a new account re-uploads context once (prompt cache is org-scoped).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.10.0",
+  "version": "0.12.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",
@@ -13,6 +13,10 @@
   "bin": {
     "tokenmaxxing": "./src/main.ts"
   },
+  "exports": {
+    ".": "./src/sdk.ts",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "README.md",

package/src/cli/status.ts

@@ -22,7 +22,10 @@ import { bar, c, fmtAgo, fmtReset } from "./render.ts";
 import type { FullUsage } from "../lib/usage.ts";
 import type { UsageWindow } from "../lib/types.ts";
 
-export async function cmdStatus(force = false): Promise<number> {
+/** `preRender` runs after sampling, right before the first output line: `watch`
+ *  keeps the previous frame on screen through the multi-second sample and
+ *  clears only when the fresh frame is ready to paint (watch(1) semantics). */
+export async function cmdStatus(force = false, preRender?: () => void): Promise<number> {
   let idx = loadAccounts();
   const cfg = loadConfig();
   const now = Date.now();
@@ -89,6 +92,7 @@ export async function cmdStatus(force = false): Promise<number> {
     saveAccounts(idx);
   });
 
+  preRender?.();
   console.log(c.dim(`threshold 5h ${cfg.thresholds.session}% · week ${cfg.thresholds.weekly}%  ·  ${idx.accounts.length} account(s)`));
   console.log();
 

package/src/cli/watch.ts

@@ -0,0 +1,57 @@
+// `tokenmaxxing watch [seconds]`: native live status (issue #3) - re-render
+// `status` on an interval instead of `watch -n 120 'tokenmaxxing status'`.
+// Plain `status` per tick, never `--force`: a ping meters real quota and starts
+// 5h session windows, so watching must stay free; each refresh costs only the
+// parked accounts' `/usage` probes the one-shot status already does.
+
+import { delay } from "es-toolkit";
+import { loadAccounts } from "../lib/state.ts";
+import { cmdStatus } from "./status.ts";
+import { c } from "./render.ts";
+
+const DEFAULT_INTERVAL_S = 120;
+/** Floor: each tick spawns a `/usage` probe per parked account (seconds each,
+ *  under the flock); anything faster than this just queues probes. */
+const MIN_INTERVAL_S = 30;
+/** Cap: past ~24.8 days the setTimeout ms overflow collapses the sleep to ~1ms
+ *  and the loop runs hot; a day is already beyond any sane watch cadence. */
+const MAX_INTERVAL_S = 86_400;
+
+/** Seconds between refreshes, clamped; null when the argument is not a positive number. */
+export function resolveWatchInterval(arg?: string): number | null {
+  if (arg === undefined) return DEFAULT_INTERVAL_S;
+  const n = Number(arg);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return Math.min(Math.max(n, MIN_INTERVAL_S), MAX_INTERVAL_S);
+}
+
+/** Home + clear screen + clear scrollback. Written only once the fresh frame is
+ *  ready to paint (cmdStatus preRender), so the previous frame stays readable
+ *  through the multi-second sample instead of blanking - watch(1) semantics. */
+const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
+
+export async function cmdWatch(intervalArg?: string): Promise<number> {
+  const intervalS = resolveWatchInterval(intervalArg);
+  if (intervalS === null) {
+    console.error(c.red(`watch interval must be a positive number of seconds, got: ${intervalArg}`));
+    return 2;
+  }
+  if (loadAccounts().accounts.length === 0) return cmdStatus();
+
+  const paintHeader = () => {
+    process.stdout.write(process.stdout.isTTY ? CLEAR : "\n");
+    console.log(c.dim(`watch · every ${intervalS}s · ${new Date().toLocaleTimeString()} · ctrl-c to quit`));
+  };
+  while (true) {
+    // One failed tick (a mid-write ~/.claude.json read, a transient probe or
+    // lock error) must not kill an hours-long monitor: report it and keep the
+    // cadence, exactly like watch(1) showing a failing command's output.
+    try {
+      await cmdStatus(false, paintHeader);
+    } catch (e) {
+      paintHeader();
+      console.error(c.red(`status failed this tick: ${String((e as Error).message ?? e)}`));
+    }
+    await delay(intervalS * 1000);
+  }
+}

package/src/lib/usage.ts

@@ -197,7 +197,7 @@ export function parseUsageText(text: string, now = Date.now()): UsageWindows | n
 /** Env-var identity/credential overrides the claude binary honors BEFORE its
  *  keychain lookup (verified 2.1.205). A probe MUST scrub every one of these or
  *  an ambient value silently meters the wrong account. */
-const CRED_ENV_OVERRIDES = [
+export const CRED_ENV_OVERRIDES = [
   "ANTHROPIC_API_KEY",
   "ANTHROPIC_AUTH_TOKEN",
   "CLAUDE_CODE_OAUTH_TOKEN",

package/src/main.ts

@@ -12,6 +12,7 @@ import { cmdInit } from "./cli/init.ts";
 import { cmdAdd } from "./cli/add.ts";
 import { cmdLs } from "./cli/ls.ts";
 import { cmdStatus } from "./cli/status.ts";
+import { cmdWatch } from "./cli/watch.ts";
 import { cmdDoctor } from "./cli/doctor.ts";
 import { cmdRm } from "./cli/rm.ts";
 import { cmdRename } from "./cli/rename.ts";
@@ -31,6 +32,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing ls")}         list pooled accounts
   ${c.cyan("tokenmaxxing status")}     accounts with 5h / weekly / per-model usage bars
   ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
+  ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} <sel> <label>
   ${c.cyan("tokenmaxxing rm")} <sel>
@@ -65,6 +67,7 @@ async function main(): Promise<number> {
     case "add": return cmdAdd();
     case "ls": return cmdLs();
     case "status": return cmdStatus(args.includes("--force"));
+    case "watch": return cmdWatch(args[1]);
     case "doctor": return cmdDoctor();
     case "rm": return cmdRm(args[1]);
     case "rename": return cmdRename(args[1], args[2]);

package/src/sdk.ts

@@ -0,0 +1,110 @@
+// Programmatic surface for pairing tokenmaxxing with the Claude Code Agent SDK
+// (personal use across your own pooled accounts - user decision 2026-07-16).
+//
+// The Agent SDK spawns a claude CLI subprocess per query() and that subprocess
+// reads credentials at spawn time: no statusLine tee, no supervisor, no
+// mid-query hot-swap. So the integration is boundary-driven - run the switch
+// decision BEFORE a spawn so it lands on the best account, and again at
+// Stop-hook turn boundaries so the NEXT spawn does; a running subprocess keeps
+// its snapshotted token either way, which is exactly the clean-boundary
+// semantics the CLI supervisor enforces with markers.
+//
+// Nothing here imports the Agent SDK: the helpers return plain values that
+// spread structurally into its Options, so tokenmaxxing keeps its exact
+// dependency set (zod, es-toolkit, ky).
+
+import { z } from "zod";
+import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealClaude } from "./lib/claudebin.ts";
+import { evaluateAndMaybeSwap, type SwapDecision } from "./lib/decide.ts";
+import { CRED_ENV_OVERRIDES } from "./lib/usage.ts";
+import { log } from "./lib/log.ts";
+
+export { evaluateAndMaybeSwap };
+export type { SwapDecision };
+
+/**
+ * Run the same greedy pace-pressure decision the hooks and check timer run
+ * (never anticipatory: there is no supervisor to pause an SDK session, so a
+ * depleted pre-park would yank it onto a known-blocked account for nothing).
+ * Call it right before query() so the subprocess spawns on the best account.
+ */
+export async function ensureBestAccount(now = Date.now()): Promise<SwapDecision> {
+  return evaluateAndMaybeSwap(now, false);
+}
+
+/** The pinned real claude binary, for Options.pathToClaudeCodeExecutable.
+ *  Never the supervisor wrapper: an SDK subprocess is headless print mode, so
+ *  the wrapper's respawn machinery buys nothing and only adds recursion risk. */
+export function claudeExecutablePath(): string {
+  return resolveRealClaude();
+}
+
+/** The pooled surface requires the DEFAULT Claude Code credential store. An
+ *  ambient config-dir override desyncs the two sides of a swap on Linux: the
+ *  swap (running in THIS process) writes the live credential where these vars
+ *  point (credDir() honors them), while the scrubbed subprocess reads the
+ *  default store - so the subprocess silently runs on a stale or absent
+ *  credential. Fail fast on both platforms rather than platform-split the
+ *  behavior (adversarial review catch, 2026-07-16). */
+const AMBIENT_STORE_VARS = ["CLAUDE_SECURESTORAGE_CONFIG_DIR", "CLAUDE_CONFIG_DIR"] as const;
+
+/**
+ * The env an SDK-spawned claude must run under to meter the POOLED live
+ * credential: every ambient credential override is scrubbed (claude honors
+ * them BEFORE its keychain/file lookup, so one inherited ANTHROPIC_API_KEY
+ * silently meters the wrong account), and the wrap depth is preset to the cap
+ * so a poisoned claudeBin pin that leads back into the tokenmaxxing wrapper
+ * aborts on first entry instead of fork-bombing.
+ *
+ * Returns a FULL environment, not a patch: the Agent SDK's Options.env
+ * REPLACES the subprocess env rather than merging over process.env (verified
+ * against the official TS reference 2026-07-16), which is what makes deleting
+ * keys from this copy effective.
+ */
+export function pooledSpawnEnv(): Record<string, string> {
+  for (const k of AMBIENT_STORE_VARS) {
+    if (process.env[k]) {
+      throw new Error(
+        `${k} is set: the pooled SDK surface requires the default Claude Code credential store (a swap writes the live credential where ${k} points, while the spawned subprocess reads the default store). Unset it in the process running tokenmaxxing.`,
+      );
+    }
+  }
+  const env: Record<string, string> = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) };
+  for (const k of CRED_ENV_OVERRIDES) delete env[k];
+  return env;
+}
+
+const PooledOptionsSchema = z.object({
+  pathToClaudeCodeExecutable: z.string(),
+  env: z.record(z.string(), z.string()),
+});
+export type PooledOptions = z.infer<typeof PooledOptionsSchema>;
+
+/** Options fragment to spread into the Agent SDK's Options. */
+export function pooledOptions(): PooledOptions {
+  return PooledOptionsSchema.parse({
+    pathToClaudeCodeExecutable: claudeExecutablePath(),
+    env: pooledSpawnEnv(),
+  });
+}
+
+/**
+ * Agent SDK Stop-hook callback (structurally matches HookCallback; the args
+ * are irrelevant here; `{}` is the documented no-op output). Runs the switch
+ * decision at the turn boundary; a swap landed here takes effect on the next
+ * subprocess spawn. Errors are caught LOUDLY (stderr + log), not rethrown:
+ * the SDK hooks reference states an unhandled exception can interrupt the
+ * agent (verified 2026-07-16), and aborting the caller's turn because a
+ * switch check failed costs more than riding out the current account. Call
+ * ensureBestAccount() directly where a broken pool should throw.
+ */
+export async function stopHookCheck(): Promise<Record<string, never>> {
+  try {
+    await evaluateAndMaybeSwap(Date.now(), false);
+  } catch (e) {
+    const err = String((e as Error).message ?? e);
+    console.error(`tokenmaxxing: switch check failed at turn boundary: ${err}`);
+    log("sdk.stop_error", { err });
+  }
+  return {};
+}