tokenmaxxing 1.157.0 → 1.159.0

package/DESIGN.md

@@ -2,7 +2,7 @@
 
 Automatic Claude Code account switching. You run `claude` exactly as always; every session starts on the pooled account with the most session-window headroom per running session, and when the account a session runs on crosses its bar (**90%** of the 5h session window or **98%** of a weekly window by default), tokenmaxxing resumes that session on a fresher account at a safe turn boundary. Works across many concurrent sessions at once, each on its own account; a fully depleted pool queues sessions first come first served onto reset targets (at most eight waiters per account; overflow waits for the next reset with room up to twice `policy.maxWaitMs` out, joining the least-crowded reset only when the horizon is full), pauses each one with a countdown, and auto-resumes at its assigned reset (further out than twice `policy.maxWaitMs`, the session stays put rather than parking for hours).
 
-> Scope: **Claude Code first (macOS + Linux, the latter since 2026-07-09).** Codex support landed in 0.13.0 (2026-07-16) with its own parallel state and supervisor; since 1.35.0 both run on one engine. Codex's verified internals live in AGENTS.md's Codex sections.
+> Scope: **Claude Code first (macOS + Linux, the latter since 2026-07-09).** Codex support landed in 0.13.0 (2026-07-16) with its own parallel state and supervisor; since 1.35.0 both run on one engine. Codex's verified internals live in `.claude/rules/codex.md`.
 >
 > Status: **implemented** (v0.1.0, 2026-07-09; per-account stores since 1.37.0, 2026-09-12). TypeScript on Bun, shipped as SOURCE with a bun-shebang bin (the compiled-binary distribution was deleted in 0.2.1); Zod validates every external-boundary payload, JSON config, es-toolkit for utilities, `flock(2)` via `bun:ffi`. Load-bearing external facts were adversarially verified against the `2.1.204` binary + docs when first shipped and re-verified against `2.1.269` for the store model (§2). What the acceptance gates showed is in §9.
 
@@ -127,7 +127,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 ---
 
 ## 8. Stack
-TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` and `codex` supervisors, the statusLine and subagent statusLine shims, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry with `--no-env-file`, so a `.env` in the working directory is not imported into the supervisor or the session (a longer `/bin/sh` shim under Nix that drops its own directory from PATH; the Stop path runs every turn, and bun's start-up stays low-millisecond). A Bun global install refreshes itself from npm on the check tick, once a day. Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). Shipping is PR-based since 2026-07-18: work reaches main only through a pull request (branch, PR, CI green, a 10-minute review wait, every review handled, merge, teardown), and a merge that changes a packed file releases itself: CI assigns the next minor version on main, publishes, and tags it (details in AGENTS.md "Release and CI"). The supervisor spawns claude with inherited stdio (a relay pipe on stdin for a stream-json session) and restores saved `stty -g` termios between runs - no PTY layer; resize and signals flow through the shared foreground process group.
+TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` and `codex` supervisors, the statusLine and subagent statusLine shims, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry with `--no-env-file`, so a `.env` in the working directory is not imported into the supervisor or the session (a longer `/bin/sh` shim under Nix that drops its own directory from PATH; the Stop path runs every turn, and bun's start-up stays low-millisecond). A Bun global install refreshes itself from npm on the check tick, once a day. Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). Shipping is PR-based since 2026-07-18: work reaches main only through a pull request (branch, PR, CI green, a 10-minute review wait, every review handled, merge, teardown), and a merge that changes a packed file releases itself: CI assigns the next minor version on main, publishes, and tags it (details in `.claude/rules/ci.md` and the `release` skill). The supervisor spawns claude with inherited stdio (a relay pipe on stdin for a stream-json session) and restores saved `stty -g` termios between runs - no PTY layer; resize and signals flow through the shared foreground process group.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.157.0",
+  "version": "1.159.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/check.ts

@@ -1,3 +1,4 @@
+import { refreshOpenRouterCredit } from "../lib/apikeys.ts";
 import { claude } from "../lib/claude.ts";
 import { codex } from "../lib/codex.ts";
 import { evaluateAndMaybeSwap, useBankedResets } from "../lib/decide.ts";
@@ -16,6 +17,7 @@ export async function cmdCheck(json = false): Promise<number> {
     d = await evaluateAndMaybeSwap(claude, now);
     await useBankedResets(codex, loadConfig(), now);
     await sampleOldest(loadConfig());
+    await refreshOpenRouterCredit();
     await maybeAutoUpdate();
   } catch (e) {
     const detail = errorMessage(e);

package/src/cli/key.ts

@@ -1,12 +1,14 @@
 import { z } from "zod";
-import { keySessions, loadApiKeys, removeApiKeySecret, saveApiKeys, settleLiveSessionCosts, writeApiKeySecret } from "../lib/apikeys.ts";
+import { isOpenRouterKey, keySessions, loadApiKeys, OPENROUTER_PREFIX, readOpenRouterCredit, removeApiKeySecret, saveApiKeys, settleLiveSessionCosts, writeApiKeySecret } from "../lib/apikeys.ts";
 import { withLock } from "../lib/lock.ts";
+import { errorMessage } from "../lib/log.ts";
 import { claudePool } from "../lib/paths.ts";
 import { readStdin } from "../lib/proc.ts";
 import type { ApiKey } from "../lib/types.ts";
 import { c, emitError, plain } from "./render.ts";
 
-const USAGE = "usage: tokenmaxxing key add <label> [credit-usd] [workspace-id] (the key on stdin) | key credit <label> <usd> | key rm <label>";
+const USAGE =
+  "usage: tokenmaxxing key add <label> [credit-usd] [workspace-id] (the key at the prompt, or on stdin when piped) | key credit <label> <usd> (an OpenRouter key takes no amount and clears its refusal) | key rm <label>";
 
 const UsdSchema = z.string().trim().min(1).transform(Number).pipe(z.number().min(0));
 
@@ -44,13 +46,9 @@ async function add(args: string[]): Promise<number> {
     return 2;
   }
   const workspaceId = workspace?.data;
-  if (process.stdin.isTTY) {
-    emitError({ message: "refusing to read the API key from a terminal, which would echo it - pipe it in: read -rs KEY && printf '%s' \"$KEY\" | tokenmaxxing key add <label> ...; unset KEY" });
-    return 2;
-  }
-  const secret = (await readStdin()).trim();
+  const secret = (process.stdin.isTTY ? (prompt("API key:") ?? "") : await readStdin()).trim();
   if (secret === "") {
-    emitError({ message: "no API key on stdin - pipe the key in, for example from your password manager" });
+    emitError({ message: "no API key given - paste it at the prompt or pipe it in" });
     return 2;
   }
   if (secret.includes("\n") || secret.includes("\r")) {
@@ -61,6 +59,19 @@ async function add(args: string[]): Promise<number> {
     emitError({ message: "that is an Admin API key, which cannot run inference - create a regular API key in the Console" });
     return 2;
   }
+  let openrouter: ApiKey["openrouter"];
+  if (secret.startsWith(OPENROUTER_PREFIX)) {
+    if (credit != null || workspaceId != null) {
+      emitError({ message: "an OpenRouter key takes no credit-usd or workspace-id - its credit left is the key's limit_remaining on OpenRouter" });
+      return 2;
+    }
+    try {
+      openrouter = await readOpenRouterCredit(secret);
+    } catch (e) {
+      emitError({ message: `could not read that OpenRouter key: ${errorMessage(e)}` });
+      return 1;
+    }
+  }
   return withLock(claudePool.lockFile, () => {
     const idx = loadApiKeys();
     const taken = findKey(idx.keys, label);
@@ -80,20 +91,24 @@ async function add(args: string[]): Promise<number> {
       spentUsd: 0,
       creditSetAt: now,
       addedAt: now,
+      ...(openrouter != null ? { openrouter } : {}),
     });
     saveApiKeys(idx);
-    console.log(`added API key ${c.bold(label)} (${credit != null ? `credit ${usd(credit)}` : "credit unknown, ranks after keys with a balance"}${workspaceId != null ? `, workspace ${workspaceId}` : ""})`);
+    const left = openrouter != null ? openrouter.remainingUsd : credit;
+    console.log(
+      `added ${openrouter != null ? "OpenRouter" : "API"} key ${c.bold(label)} (${left != null ? `credit ${usd(left)}` : "credit unknown, ranks after keys with a balance"}${workspaceId != null ? `, workspace ${workspaceId}` : ""})`,
+    );
     return 0;
   });
 }
 
 async function credit(args: string[]): Promise<number> {
   const [label, amountRaw] = args;
-  if (!label || amountRaw == null || args.length > 2) {
+  if (!label || args.length > 2) {
     emitError({ message: USAGE, paint: plain });
     return 2;
   }
-  const amount = parseUsd(amountRaw);
+  const amount = amountRaw == null ? undefined : parseUsd(amountRaw);
   if (amount === null) return 2;
   return withLock(claudePool.lockFile, () => {
     const idx = loadApiKeys();
@@ -102,6 +117,20 @@ async function credit(args: string[]): Promise<number> {
       emitError({ message: `no API key is labeled "${label}"` });
       return 1;
     }
+    if (isOpenRouterKey(key)) {
+      if (amount != null) {
+        emitError({ message: `${key.label} is an OpenRouter key - its credit left is the key's limit_remaining, read from OpenRouter on every check tick; set the limit on OpenRouter. \`key credit ${key.label}\` with no amount clears a refusal` });
+        return 1;
+      }
+      key.refusedAt = undefined;
+      saveApiKeys(idx);
+      console.log(`cleared the refusal on ${c.bold(key.label)}`);
+      return 0;
+    }
+    if (amount == null) {
+      emitError({ message: USAGE, paint: plain });
+      return 2;
+    }
     key.creditUsd = amount;
     key.spentUsd = 0;
     key.creditSetAt = Date.now();

package/src/entries/supervisor.ts

@@ -332,7 +332,7 @@ function systemLine(sid: string, text: string): string {
 }
 
 function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; onKey: boolean }): string {
-  const where = input.onKey ? "on an Anthropic API key, because every pooled account is at its limit or the previous key ran out" : "on an account with quota headroom";
+  const where = input.onKey ? "on an API key, because every pooled account is at its limit or the previous key ran out" : "on an account with quota headroom";
   const moved = input.compacted
     ? `tokenmaxxing compacted this conversation and resumed the session ${where}.`
     : `tokenmaxxing resumed this session ${where}.`;

package/src/lib/apikeys.ts

@@ -1,13 +1,16 @@
 import { chmodSync, closeSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { countBy, isEqual, sortBy } from "es-toolkit";
+import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
+import { http, safeErrorDetail } from "./http.ts";
 import { withLock } from "./lock.ts";
-import { claudePool, optionalEnv, paths } from "./paths.ts";
+import { errorMessage, log } from "./log.ts";
+import { claudePool, env, optionalEnv, paths } from "./paths.ts";
 import { livingPresences } from "./presence.ts";
 import type { ApiKeyPool } from "./provider.ts";
 import { readJsonFile } from "./state.ts";
-import { ApiKeysIndexSchema, SessionCostSchema, type ApiKey, type ApiKeysIndex, type SessionCost } from "./types.ts";
+import { ApiKeysIndexSchema, JsonTextSchema, SessionCostSchema, type ApiKey, type ApiKeysIndex, type SessionCost } from "./types.ts";
 
 export const API_KEY_ENV = "TOKENMAXXING_API_KEY_ID";
 export const API_KEY_FD = 3;
@@ -15,7 +18,58 @@ export const API_KEY_FD = 3;
 export function apiKeyEnv(env: Record<string, string | undefined>, key: ApiKey): Record<string, string | undefined> {
   const header = key.workspaceId == null ? null : `anthropic-workspace-id: ${key.workspaceId}`;
   const headers = header == null ? env.ANTHROPIC_CUSTOM_HEADERS : env.ANTHROPIC_CUSTOM_HEADERS ? `${env.ANTHROPIC_CUSTOM_HEADERS}\n${header}` : header;
-  return { ...env, CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR: String(API_KEY_FD), ...(headers != null ? { ANTHROPIC_CUSTOM_HEADERS: headers } : {}) };
+  return {
+    ...env,
+    CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR: String(API_KEY_FD),
+    ...(headers != null ? { ANTHROPIC_CUSTOM_HEADERS: headers } : {}),
+    ...(isOpenRouterKey(key) ? { ANTHROPIC_BASE_URL: OPENROUTER_URL } : {}),
+  };
+}
+
+export const OPENROUTER_PREFIX = "sk-or-";
+
+export function isOpenRouterKey(key: ApiKey): boolean {
+  return readApiKey(key).startsWith(OPENROUTER_PREFIX);
+}
+
+const OPENROUTER_URL = env("TOKENMAXXING_OPENROUTER_URL", "https://openrouter.ai/api");
+const OPENROUTER_READ_DEADLINE_MS = 10_000;
+const OpenRouterKeySchema = z.looseObject({ data: z.looseObject({ limit_remaining: z.number().nullable() }) });
+
+export async function readOpenRouterCredit(secret: string): Promise<NonNullable<ApiKey["openrouter"]>> {
+  const at = Date.now();
+  const res = await http.get(`${OPENROUTER_URL}/v1/key`, { headers: { Authorization: `Bearer ${secret}` }, signal: AbortSignal.timeout(OPENROUTER_READ_DEADLINE_MS) });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`OpenRouter key read answered HTTP ${res.status}: ${safeErrorDetail({ text })}`);
+  return { remainingUsd: OpenRouterKeySchema.parse(JsonTextSchema.safeParse(text).data).data.limit_remaining, at };
+}
+
+export async function refreshOpenRouterCredit(): Promise<void> {
+  if (!existsSync(claudePool.apiKeysJson)) return;
+  const reads = await Promise.all(
+    availableKeys().map(async (k) => {
+      try {
+        if (!isOpenRouterKey(k)) return null;
+        return { id: k.id, credit: await readOpenRouterCredit(readApiKey(k).trim()) };
+      } catch (e) {
+        log("apikey.openrouter_read_failed", { key: k.id, err: errorMessage(e) });
+        return null;
+      }
+    }),
+  );
+  const landed = reads.filter((r) => r != null);
+  if (landed.length === 0) return;
+  await withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    let changed = false;
+    for (const r of landed) {
+      const key = idx.keys.find((k) => k.id === r.id);
+      if (key == null || r.credit.at <= (key.openrouter?.at ?? 0)) continue;
+      key.openrouter = r.credit;
+      changed = true;
+    }
+    if (changed) saveApiKeys(idx);
+  });
 }
 
 export function readApiKey(key: ApiKey): string {
@@ -57,6 +111,7 @@ export function removeApiKeySecret(id: string): void {
 }
 
 export function creditLeft(k: ApiKey): number | null {
+  if (k.openrouter != null) return k.openrouter.remainingUsd;
   return k.creditUsd == null ? null : k.creditUsd - k.spentUsd;
 }
 
@@ -157,7 +212,7 @@ export async function foldSessionCost(sid: string, keyId: string | null, restore
       const prev = idx.baselines[seen.sessionId];
       if (prev != null && seen.usd <= prev.usd) continue;
       const delta = Math.max(0, seen.usd - (prev?.usd ?? restoredCost(seen.sessionId)));
-      if (key) key.spentUsd += delta;
+      if (key && !isOpenRouterKey(key)) key.spentUsd += delta;
       idx.baselines[seen.sessionId] = { usd: seen.usd, at: Date.now() };
       changed = true;
     }

package/src/lib/types.ts

@@ -181,6 +181,7 @@ export const ApiKeySchema = z.object({
   creditSetAt: z.number(),
   refusedAt: z.number().optional(),
   addedAt: z.number(),
+  openrouter: z.object({ remainingUsd: z.number().nullable(), at: z.number() }).optional(),
 });
 export type ApiKey = z.infer<typeof ApiKeySchema>;
 

package/src/main.ts

@@ -62,8 +62,8 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex | --grok] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex | --grok] <sel>
-  ${c.cyan("tokenmaxxing key add")} <label> [credit-usd] [workspace-id]  store an Anthropic API key read from stdin; Claude sessions run on it only while every pooled Claude account is at its limit (workspace-id: for a key that spans several workspaces)
-  ${c.cyan("tokenmaxxing key credit")} <label> <usd>  set the key's balance as the Console shows it and restart its spend count
+  ${c.cyan("tokenmaxxing key add")} <label> [credit-usd] [workspace-id]  store an Anthropic or OpenRouter (sk-or-...) API key read from stdin or the prompt; Claude sessions run on it only while every pooled Claude account is at its limit (workspace-id: for a key that spans several workspaces; an OpenRouter key takes neither argument and reads its credit from OpenRouter)
+  ${c.cyan("tokenmaxxing key credit")} <label> <usd>  set the key's balance as the Console shows it and restart its spend count (an OpenRouter key takes no amount: key credit <label> clears its refusal)
   ${c.cyan("tokenmaxxing key rm")} <label>  delete the key and its stored secret (refused while a session runs on it)
   ${c.cyan("tokenmaxxing seat")} <pid>  lend one pooled Claude account to an unattended consumer until <pid> exits: prints the store directory to set as CLAUDE_SECURESTORAGE_CONFIG_DIR (the directory itself, as its owner, never a copy of its credential); host sessions and other borrowers share the account; exit 1 = none usable
   ${c.cyan("tokenmaxxing seat")} <pid> --store <id>  lend the Claude store with that 8-character id instead of the ranked pick, checking only that it is pooled, holds a usable credential, and is not flagged for reauthentication; bars, the credits flag, and holds are the caller's job; exit 0 = granted, 1 = the store is unusable, 2 = unknown store, <pid> already holds another store, or bad usage