tokenmaxxing 0.11.0 → 0.13.0

package/src/lib/paths.ts

@@ -4,12 +4,15 @@
 
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { z } from "zod";
 
 const HOME = homedir();
 
+/** A set env override; empty or unset parses to undefined and the fallback applies. */
+const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
+
 function env(name: string, fallback: string): string {
-  const v = process.env[name];
-  return v && v.length > 0 ? v : fallback;
+  return EnvOverrideSchema.parse(process.env[name]) ?? fallback;
 }
 
 /** Root of all tokenmaxxing config + state. Default ~/.config/tokenmaxxing. */
@@ -52,6 +55,37 @@ export function claudeLockPath(): string {
   return env("TOKENMAXXING_CLAUDE_LOCK", join(HOME, ".claude.lock"));
 }
 
+/** Codex home: where the live auth.json lives. Test override first, then
+ *  codex's own CODEX_HOME env, then its default ~/.codex. */
+const CODEX_HOME = env("TOKENMAXXING_CODEX_HOME", env("CODEX_HOME", join(HOME, ".codex")));
+
+export const codexPaths = {
+  home: CODEX_HOME,
+  /** the live credential file (codex file-mode store; verified 0.144.4/5). */
+  authJson: join(CODEX_HOME, "auth.json"),
+  /** user-level hook declarations codex reads (verified against the binary + docs). */
+  hooksJson: join(CODEX_HOME, "hooks.json"),
+  /** tokenmaxxing's codex pool state, parallel to the claude files in TM_HOME. */
+  accountsJson: join(TM_HOME, "codex-accounts.json"),
+  lastSwapJson: join(TM_HOME, "codex-lastswap.json"),
+  lockFile: join(TM_HOME, "codex-lock"),
+  /** parked auth.json blobs: 0600 files on BOTH platforms (codex's own store is
+   *  a plaintext file, and parked blobs at ~6KB would risk the security(1)
+   *  write-size trap that once truncated a 4.3KB claude blob). */
+  credsDir: join(TM_HOME, "codex-creds"),
+  onboardDir: join(TM_HOME, "codex-onboard"),
+  respawnDir: join(TM_HOME, "codex-respawn"),
+  /** one file per RUNNING supervised codex session: {accountId, pid, ts}. A
+   *  running account's parked token must never be refreshed or targeted (its
+   *  live rotations supersede the parked copy, and reuse is punished). */
+  presenceDir: join(TM_HOME, "codex-live"),
+} as const;
+
+/** Per-account parked codex credential file name: tokenmaxxing-codex-<id8>. */
+export function codexCredItemFor(accountId: string): string {
+  return `tokenmaxxing-codex-${accountId.slice(0, 8)}`;
+}
+
 /** The macOS login-keychain generic-password the live `claude` reads. */
 export const keychain = {
   service: env("TOKENMAXXING_KEYCHAIN_SERVICE", "Claude Code-credentials"),
@@ -88,8 +122,12 @@ export function namespacedCredService(configDirRaw: string): string {
 
 /** Resolve the REAL claude binary (never our shim). Order: explicit env, config, PATH scan. */
 export function realClaudeBinFromEnv(): string | undefined {
-  const v = process.env.TOKENMAXXING_CLAUDE_BIN;
-  return v && v.length > 0 ? v : undefined;
+  return EnvOverrideSchema.parse(process.env.TOKENMAXXING_CLAUDE_BIN);
+}
+
+/** Same override hook for the real codex binary (tests / relocation). */
+export function realCodexBinFromEnv(): string | undefined {
+  return EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_BIN);
 }
 
 export { HOME };

package/src/lib/state.ts

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync, rmSync, statSync, utimesSync } from "node:fs";
 import { isEqual } from "es-toolkit";
 import { z } from "zod";
-import { paths, realClaudeBinFromEnv } from "./paths.ts";
+import { paths, realClaudeBinFromEnv, realCodexBinFromEnv } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
 import {
   AccountsIndexSchema,
@@ -24,6 +24,7 @@ const DEFAULT_CONFIG: Config = {
   // cheap to sit out, weekly quota is use-it-or-lose-it so it drains to 98.
   thresholds: { session: 95, weekly: 98 },
   claudeBin: "",
+  codexBin: "",
   // per-model weekly caps exist only for Sonnet and Fable (no Opus-only quota,
   // per the user 2026-07-12), and only Fable's is worth switching on.
   // greedySessionFloor 50: half a session window buys the swap (user 2026-07-16).
@@ -35,6 +36,7 @@ const ConfigFileSchema = z
   .object({
     thresholds: z.object({ session: z.number(), weekly: z.number() }).partial(),
     claudeBin: z.string(),
+    codexBin: z.string(),
     policy: z
       .object({
         projectionMargin: z.number(),
@@ -61,6 +63,7 @@ export function loadConfig(): Config {
     cfg.thresholds.session = p.thresholds?.session ?? cfg.thresholds.session;
     cfg.thresholds.weekly = p.thresholds?.weekly ?? cfg.thresholds.weekly;
     cfg.claudeBin = p.claudeBin ?? cfg.claudeBin;
+    cfg.codexBin = p.codexBin ?? cfg.codexBin;
     cfg.policy.projectionMargin = p.policy?.projectionMargin ?? cfg.policy.projectionMargin;
     cfg.policy.greedySessionFloor = p.policy?.greedySessionFloor ?? cfg.policy.greedySessionFloor;
     cfg.policy.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
@@ -69,9 +72,11 @@ export function loadConfig(): Config {
       cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
     }
   }
-  // env override wins for the claude binary (tests / relocation)
+  // env overrides win for the real binaries (tests / relocation)
   const envBin = realClaudeBinFromEnv();
   if (envBin) cfg.claudeBin = envBin;
+  const envCodexBin = realCodexBinFromEnv();
+  if (envCodexBin) cfg.codexBin = envCodexBin;
   return ConfigSchema.parse(cfg);
 }
 

package/src/lib/types.ts

@@ -122,6 +122,8 @@ export type Thresholds = z.infer<typeof ThresholdsSchema>;
 export const ConfigSchema = z.object({
   thresholds: ThresholdsSchema,
   claudeBin: z.string(),
+  /** the real codex binary (empty = resolve from PATH); pinned by `init --codex`. */
+  codexBin: z.string(),
   policy: z.object({
     projectionMargin: z.number(),
     /** session-used % at which the greedy convergence engages: from here on,
@@ -204,3 +206,90 @@ export const RolesResponseSchema = z.looseObject({
   organization_name: z.string(),
 });
 export type RolesResponse = z.infer<typeof RolesResponseSchema>;
+
+// ---- Codex pool ------------------------------------------------------------
+
+/** `tokens` inside $CODEX_HOME/auth.json (verified against a live 0.144.4
+ *  auth.json). Loose: preserve unknown siblings so a harvest and reinstall
+ *  round-trip is lossless. */
+export const CodexTokensSchema = z.looseObject({
+  id_token: z.string(),
+  access_token: z.string(),
+  refresh_token: z.string(),
+  account_id: z.string().optional(),
+});
+export type CodexTokens = z.infer<typeof CodexTokensSchema>;
+
+/** The whole auth.json. Loose: auth_mode, OPENAI_API_KEY (may be null), and
+ *  future siblings ride along verbatim. */
+export const CodexAuthJsonSchema = z.looseObject({
+  tokens: CodexTokensSchema,
+  last_refresh: z.string().optional(),
+});
+export type CodexAuthJson = z.infer<typeof CodexAuthJsonSchema>;
+
+/** One rate-limit window as tokenmaxxing stores it: percent used, absolute
+ *  epoch ms reset, and the server-declared duration. Codex windows are
+ *  duration-driven (the weekly window is PRIMARY on plans whose 5h window was
+ *  removed in July 2026), so classification must go by windowSeconds, never
+ *  by primary/secondary position. */
+export const CodexWindowSchema = z.object({
+  usedPercentage: z.number(),
+  resetsAt: z.number().nullable(),
+  windowSeconds: z.number().nullable(),
+});
+export type CodexWindow = z.infer<typeof CodexWindowSchema>;
+
+/** Everything one free usage read yields: the token's OWN identity (the codex
+ *  analog of the claude roles endpoint: labels drift, the token cannot lie)
+ *  plus every rate-limit window, aggregate and per-limit-family. */
+export const CodexUsageSchema = z.object({
+  accountId: z.string(),
+  email: z.string().nullable(),
+  planType: z.string().nullable(),
+  aggregate: z.array(CodexWindowSchema),
+  perLimit: z.record(z.string(), z.array(CodexWindowSchema)),
+});
+export type CodexUsage = z.infer<typeof CodexUsageSchema>;
+
+/** A pooled codex account (codex-accounts.json - NON-secret). */
+export const CodexAccountSchema = z.object({
+  accountId: z.string(),
+  email: z.string().nullable(),
+  label: z.string(),
+  planType: z.string().nullable(),
+  credFile: z.string(),
+  addedAt: z.string(),
+  needsReauth: z.boolean().optional(),
+  lastUsage: z
+    .object({
+      aggregate: z.array(CodexWindowSchema),
+      perLimit: z.record(z.string(), z.array(CodexWindowSchema)),
+    })
+    .optional(),
+  lastUsageAt: z.number().optional(),
+});
+export type CodexAccount = z.infer<typeof CodexAccountSchema>;
+
+export const CodexAccountsIndexSchema = z.object({
+  version: z.literal(1),
+  activeAccountId: z.string().nullable(),
+  accounts: z.array(CodexAccountSchema).default([]),
+});
+export type CodexAccountsIndex = z.infer<typeof CodexAccountsIndexSchema>;
+
+/** Codex Stop-hook stdin (verified against the 0.144.4 binary wire schema and
+ *  the official hooks reference): only what the swap trigger consumes. */
+export const CodexStopStdinSchema = z.looseObject({
+  session_id: z.string().optional(),
+  hook_event_name: z.string().optional(),
+});
+
+/** The codex supervisor's respawn marker payload: which session to resume and
+ *  under which account label (for the switch banner). */
+export const CodexRespawnMarkerSchema = z.object({
+  account: z.string(),
+  sessionId: z.string().nullable(),
+  ts: z.number(),
+});
+export type CodexRespawnMarker = z.infer<typeof CodexRespawnMarkerSchema>;

package/src/main.ts

@@ -10,8 +10,14 @@ import { runStopHook } from "./entries/stophook.ts";
 import { runSessionStart } from "./entries/sessionstart.ts";
 import { cmdInit } from "./cli/init.ts";
 import { cmdAdd } from "./cli/add.ts";
+import { cmdCodexAdd } from "./cli/codexadd.ts";
+import { cmdCodexInit } from "./cli/codexinit.ts";
+import { cmdCodexSwitch } from "./cli/codexswitch.ts";
+import { runCodexSupervisor } from "./entries/codexsupervisor.ts";
+import { runCodexStopHook } from "./entries/codexstophook.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";
@@ -27,10 +33,14 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing switch")} [sel]  switch to the best (or a specific) account; no-op when already on it
   ${c.cyan("tokenmaxxing check")}      evaluate once, switch if over threshold (run by the periodic timer)
   ${c.cyan("tokenmaxxing init")}       import the current account + install supervisor & hooks
+  ${c.cyan("tokenmaxxing init --codex")}  same for codex: import login, install codex supervisor + Stop hook (trust it via /hooks)
   ${c.cyan("tokenmaxxing add")}        register an additional account (isolated login)
+  ${c.cyan("tokenmaxxing add --codex")}   register an additional codex account (isolated login)
+  ${c.cyan("tokenmaxxing switch --codex")} [sel]  switch the codex pool (takes effect on next codex start)
   ${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>
@@ -52,19 +62,24 @@ async function main(): Promise<number> {
   if (argv0 === "claude" || sub === "__supervise") {
     return runSupervisor(sub === "__supervise" ? args.slice(1) : args);
   }
+  if (argv0 === "codex" || sub === "__supervise-codex") {
+    return runCodexSupervisor({ argv: sub === "__supervise-codex" ? args.slice(1) : args });
+  }
 
   switch (sub) {
     case "__statusline": return runStatusline();
     case "__stop-hook": return runStopHook();
     case "__session-start": return runSessionStart();
+    case "__codex-stop-hook": return runCodexStopHook();
     case undefined: return cmdStatus(); // bare `tokenmaxxing` / `xx` → status
     case "--force": return cmdStatus(true); // bare `xx --force` → status --force
-    case "switch": return cmdSwitch(args[1]);
+    case "switch": return args[1] === "--codex" ? cmdCodexSwitch(args[2]) : cmdSwitch(args[1]);
     case "check": return cmdCheck();
-    case "init": return cmdInit();
-    case "add": return cmdAdd();
+    case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
+    case "add": return args.includes("--codex") ? cmdCodexAdd() : 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

@@ -102,7 +102,7 @@ export async function stopHookCheck(): Promise<Record<string, never>> {
   try {
     await evaluateAndMaybeSwap(Date.now(), false);
   } catch (e) {
-    const err = String((e as Error).message ?? e);
+    const err = e instanceof Error ? e.message : String(e);
     console.error(`tokenmaxxing: switch check failed at turn boundary: ${err}`);
     log("sdk.stop_error", { err });
   }