tokenmaxxing 1.30.0 → 1.31.0

package/DESIGN.md

@@ -30,7 +30,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
 - A `claude` **supervisor** on your PATH ahead of the real binary (`~/.config/tokenmaxxing/bin/claude`), or a shell function - you invoke it identically.
 - Four `~/.claude/settings.json` entries (merged - other settings keys are preserved, but the `statusLine` slot is taken over): the tokenmaxxing `statusLine` renderer (native since 2026-07-11; it also tees usage), a `subagentStatusLine` (per-subagent rows in the agents panel), a `Stop` hook, a `SessionStart` hook.
 - **`~/.config/tokenmaxxing/`** - the single home for config and state:
-  - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin pins, policy.*); defaults merge at read time, `xx config` edits it.
+  - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin pins, policy.*); defaults apply at read time, `xx config` prints the path and the effective values, and edits happen in an editor.
   - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, label, lastUsage, lastPerModel, needsReauth, ...}` (window resets live inside lastUsage).
   - `usage.json` - live usage, written by the statusLine shim.
   - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal, depleted-pool waits only).

package/README.md

@@ -69,7 +69,7 @@ claude                  # use claude as always
 | `tokenmaxxing switch [sel]` | switch the claude pool: bare picks the best account (no-op when the current one wins), a selector targets one |
 | `tokenmaxxing switch --codex [sel]` | switch the codex pool (takes effect on the next codex start) |
 | `tokenmaxxing status [--cached]` | accounts with 5h / weekly usage bars, active + exhausted-until-reset; `--cached` renders the stored figures without sampling |
-| `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
+| `tokenmaxxing config` | the config path and the effective values; edit the file in an editor, a bad value fails the next load with the field name |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
 | `tokenmaxxing rename [--codex] <sel> <label>` / `rm [--codex] <sel>` | manage the pool (`--codex` targets the codex pool: one email can hold both a claude and a codex account) |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.30.0",
+  "version": "1.31.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",

package/src/cli/config.ts

@@ -1,242 +1,25 @@
-import { existsSync, readFileSync } from "node:fs";
-import { isPlainObject } from "es-toolkit";
-import { get, set, unset } from "es-toolkit/compat";
-import { z } from "zod";
-import { paths, realClaudeBinFromEnv, realCodexBinFromEnv } from "../lib/paths.ts";
-import { ConfigFileSchema, loadConfig, mergeConfigFile } from "../lib/state.ts";
-import { writeFileAtomic } from "../lib/atomic.ts";
+import { paths } from "../lib/paths.ts";
+import { loadConfig } from "../lib/state.ts";
+import type { Config } from "../lib/types.ts";
 import { c, emitError, emitJson } from "./render.ts";
 
-export const KNOWN_KEYS = [
-  "thresholds.session",
-  "thresholds.weekly",
-  "claudeBin",
-  "codexBin",
-  "policy.projectionMargin",
-  "policy.switchModels",
-  "policy.usagePollTtlMs",
-  "policy.maxWaitMs",
-  "policy.checkIntervalMs",
-] as const;
-
-const TIMER_REWRITE_NOTE = "note: run `tokenmaxxing init` to rewrite the periodic timer at the new tick";
-
-const RawFileSchema = z.record(z.string(), z.unknown());
-
-function readRawFile(): Record<string, unknown> {
-  if (!existsSync(paths.configJson)) return {};
-  return RawFileSchema.parse(JSON.parse(readFileSync(paths.configJson, "utf8")));
-}
-
-function writeRawFile(input: { raw: Record<string, unknown> }): void {
-  writeFileAtomic(paths.configJson, JSON.stringify(input.raw, null, 2) + "\n");
-}
-
-function dottedKeys(obj: Record<string, unknown>): string[] {
-  const keys: string[] = [];
-  for (const [key, value] of Object.entries(obj)) {
-    if (isPlainObject(value)) {
-      for (const nested of Object.keys(value)) keys.push(`${key}.${nested}`);
-      continue;
-    }
-    keys.push(key);
-  }
-  return keys;
-}
-
-function unknownFileKeys(raw: Record<string, unknown>): string[] {
-  const known = new Set<string>(KNOWN_KEYS);
-  return dottedKeys(raw).filter((key) => !known.has(key));
-}
-
-function isKnownKey(key: string): boolean {
-  return KNOWN_KEYS.some((known) => known === key);
-}
-
-function envSourceFor(key: string): string | null {
-  if (key === "claudeBin" && realClaudeBinFromEnv()) return "TOKENMAXXING_CLAUDE_BIN";
-  if (key === "codexBin" && realCodexBinFromEnv()) return "TOKENMAXXING_CODEX_BIN";
-  return null;
-}
-
-function sourceOf(input: { key: string; raw: Record<string, unknown> }): { source: "env" | "file" | "default"; env: string | null } {
-  const env = envSourceFor(input.key);
-  if (env) return { source: "env", env };
-  return { source: get(input.raw, input.key) !== undefined ? "file" : "default", env: null };
-}
-
-function unknownKey(input: { key: string; json: boolean }): number {
-  emitError({
-    json: input.json,
-    message: `unknown config key: ${input.key}`,
-    notes: [`known keys: ${KNOWN_KEYS.join(", ")}`],
-    extra: { knownKeys: KNOWN_KEYS },
-  });
-  return 1;
-}
-
-function printEffective(json: boolean): number {
-  const effective = loadConfig();
-  const raw = readRawFile();
-  const unknown = unknownFileKeys(raw);
-  if (json) {
-    const sources: Record<string, string> = {};
-    const envOverrides: Record<string, string> = {};
-    for (const key of KNOWN_KEYS) {
-      const { source, env } = sourceOf({ key, raw });
-      sources[key] = source;
-      if (env) envOverrides[key] = env;
-    }
-    emitJson({ ok: true, path: paths.configJson, config: effective, sources, envOverrides, unknownKeys: unknown });
-    return 0;
-  }
-  console.log(c.dim(`config.json: ${paths.configJson}`));
-  for (const key of KNOWN_KEYS) {
-    const { source, env } = sourceOf({ key, raw });
-    const painted = source === "env" ? c.yellow(`env ${env}`) : source === "file" ? c.green("file") : c.dim("default");
-    console.log(`  ${key.padEnd(28)} ${JSON.stringify(get(effective, key))}  ${painted}`);
-  }
-  if (unknown.length > 0) {
-    console.log();
-    console.log(c.yellow(`unknown keys in the file (ignored by the loader): ${unknown.join(", ")}`));
-    console.log(c.dim("run `tokenmaxxing config tidy` to drop them"));
-  }
-  return 0;
-}
-
-function cmdGet(key: string, json: boolean): number {
-  if (!isKnownKey(key)) return unknownKey({ key, json });
-  const value = get(loadConfig(), key);
-  if (json) {
-    emitJson({ ok: true, key, value, source: sourceOf({ key, raw: readRawFile() }).source });
-    return 0;
+export function cmdConfig(args: string[], json = false): number {
+  if (args.length > 0) {
+    emitError({ json, message: `unknown config option: ${args[0]} (config takes no options; edit ${paths.configJson} in an editor)` });
+    return 2;
   }
-  console.log(JSON.stringify(value));
-  return 0;
-}
-
-function parseValue(text: string): unknown {
+  let effective: Config;
   try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-
-function cmdSet(key: string, valueText: string, json: boolean): number {
-  if (!isKnownKey(key)) return unknownKey({ key, json });
-  const raw = readRawFile();
-  const next = structuredClone(raw);
-  set(next, key, parseValue(valueText));
-  const validated = ConfigFileSchema.safeParse(next);
-  if (!validated.success) {
-    emitError({ json, message: `rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}` });
-    return 1;
-  }
-  const mergedCheck = mergeConfigFile(validated.data);
-  if (!mergedCheck.ok) {
-    emitError({ json, message: `rejected: ${mergedCheck.detail}` });
-    return 1;
-  }
-  writeRawFile({ raw: next });
-  const beforeFile = get(raw, key);
-  const env = envSourceFor(key);
-  if (json) {
-    emitJson({ ok: true, key, before: beforeFile === undefined ? null : beforeFile, after: get(next, key), envOverride: env });
-    return 0;
-  }
-  console.log(
-    `${key}: ${beforeFile === undefined ? "(default)" : JSON.stringify(beforeFile)} -> ${JSON.stringify(get(next, key))}`,
-  );
-  if (env) console.log(c.yellow(`note: ${env} is set and overrides the file value in this environment`));
-  if (key === "policy.checkIntervalMs") console.log(c.yellow(TIMER_REWRITE_NOTE));
-  return 0;
-}
-
-function pruneEmptyParents(raw: Record<string, unknown>): void {
-  for (const [topKey, value] of Object.entries(raw)) {
-    if (isPlainObject(value) && Object.keys(value).length === 0) {
-      delete raw[topKey];
-    }
-  }
-}
-
-function cmdUnset(key: string, json: boolean): number {
-  if (!isKnownKey(key)) return unknownKey({ key, json });
-  const raw = readRawFile();
-  if (get(raw, key) === undefined) {
-    if (json) emitJson({ ok: true, key, unset: false, value: get(loadConfig(), key) });
-    else console.log(c.dim(`${key} has no file override (default already applies)`));
-    return 0;
-  }
-  const next = structuredClone(raw);
-  unset(next, key);
-  pruneEmptyParents(next);
-  const validated = ConfigFileSchema.safeParse(next);
-  if (!validated.success) {
-    emitError({ json, message: `rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}` });
-    return 1;
-  }
-  const mergedCheck = mergeConfigFile(validated.data);
-  if (!mergedCheck.ok) {
-    emitError({ json, message: `rejected: ${mergedCheck.detail} (adjust the conflicting override before unsetting ${key})` });
+    effective = loadConfig();
+  } catch (e) {
+    emitError({ json, message: e instanceof Error ? e.message : String(e), extra: { path: paths.configJson } });
     return 1;
   }
-  writeRawFile({ raw: next });
-  const value = get(loadConfig(), key);
   if (json) {
-    emitJson({ ok: true, key, unset: true, value });
-    return 0;
-  }
-  console.log(`${key} unset -> ${JSON.stringify(value)} (default)`);
-  if (key === "policy.checkIntervalMs") console.log(c.yellow(TIMER_REWRITE_NOTE));
-  return 0;
-}
-
-function cmdTidy(json: boolean): number {
-  const raw = readRawFile();
-  const dropped = unknownFileKeys(raw);
-  const parsed = ConfigFileSchema.parse(raw);
-  const next = RawFileSchema.parse(JSON.parse(JSON.stringify(parsed)));
-  const models = get(next, "policy.switchModels");
-  const normalized = Array.isArray(models) ? models.map((model) => String(model).toLowerCase()) : null;
-  const casingChanged = normalized != null && JSON.stringify(normalized) !== JSON.stringify(models);
-  if (normalized != null) set(next, "policy.switchModels", normalized);
-  pruneEmptyParents(next);
-
-  const changed = JSON.stringify(next) !== JSON.stringify(raw);
-  if (changed) writeRawFile({ raw: next });
-  if (json) {
-    emitJson({ ok: true, changed, droppedKeys: dropped, casingNormalized: casingChanged });
-    return 0;
-  }
-  if (!changed) {
-    console.log(c.dim("nothing to tidy"));
+    emitJson({ ok: true, path: paths.configJson, effective });
     return 0;
   }
-  if (dropped.length > 0) console.log(`dropped unknown keys: ${dropped.join(", ")}`);
-  if (casingChanged) console.log("normalized switchModels casing");
-  if (dropped.length === 0 && !casingChanged) console.log("canonicalized file layout (pruned empty sections / key order)");
+  console.log(c.dim(`config.json: ${paths.configJson}`));
+  console.log(JSON.stringify(effective, null, 2));
   return 0;
 }
-
-export function cmdConfig(args: string[], json = false): number {
-  const [sub, key, value] = args;
-  try {
-    if (sub === undefined) return printEffective(json);
-    if (sub === "get" && key !== undefined) return cmdGet(key, json);
-    if (sub === "set" && key !== undefined && value !== undefined) return cmdSet(key, value, json);
-    if (sub === "unset" && key !== undefined) return cmdUnset(key, json);
-    if (sub === "tidy") return cmdTidy(json);
-  } catch (e) {
-    emitError({
-      json,
-      message: `config.json is unreadable: ${e instanceof Error ? e.message : String(e)}`,
-      notes: [`fix or delete ${paths.configJson} (defaults apply when it is absent), then re-run`],
-      extra: { path: paths.configJson },
-    });
-    return 1;
-  }
-  emitError({ json, message: "usage: tokenmaxxing config [get <key> | set <key> <value> | unset <key> | tidy]" });
-  return 2;
-}

package/src/lib/state.ts

@@ -15,91 +15,26 @@ import {
   type UsageState,
 } from "./types.ts";
 
-const DEFAULT_CONFIG: Config = {
-  thresholds: { session: 90, weekly: 98 },
-  claudeBin: "",
-  codexBin: "",
-  policy: {
-    projectionMargin: 0,
-    switchModels: ["fable"],
-    usagePollTtlMs: 90_000,
-    maxWaitMs: 3_600_000,
-    checkIntervalMs: 60_000,
-  },
-};
-
-const PercentSchema = z.number().min(0).max(100);
-
-export const ConfigFileSchema = z
-  .object({
-    thresholds: z.object({ session: PercentSchema, weekly: PercentSchema }).partial(),
-    claudeBin: z.string(),
-    codexBin: z.string(),
-    policy: z
-      .object({
-        projectionMargin: PercentSchema,
-        switchModels: z.array(z.string()),
-        usagePollTtlMs: z.number().int().positive(),
-        maxWaitMs: z.number().int().positive(),
-        checkIntervalMs: z.number().int().min(10_000),
-      })
-      .partial(),
-  })
-  .partial();
-
-const MergeOutcomeSchema = z.union([
-  z.object({ ok: z.literal(true), config: ConfigSchema }),
-  z.object({ ok: z.literal(false), detail: z.string() }),
-]);
-export type MergeOutcome = z.infer<typeof MergeOutcomeSchema>;
-
-export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutcome {
-  const cfg: Config = {
-    ...DEFAULT_CONFIG,
-    thresholds: { ...DEFAULT_CONFIG.thresholds },
-    policy: { ...DEFAULT_CONFIG.policy },
-  };
-  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.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
-  cfg.policy.maxWaitMs = p.policy?.maxWaitMs ?? cfg.policy.maxWaitMs;
-  cfg.policy.checkIntervalMs = p.policy?.checkIntervalMs ?? cfg.policy.checkIntervalMs;
-  if (p.policy?.switchModels) {
-    cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
-  }
-  const envBin = realClaudeBinFromEnv();
-  if (envBin) cfg.claudeBin = envBin;
-  const envCodexBin = realCodexBinFromEnv();
-  if (envCodexBin) cfg.codexBin = envCodexBin;
-  const merged = ConfigSchema.safeParse(cfg);
-  if (!merged.success) {
-    return { ok: false, detail: merged.error.issues.map((issue) => issue.message).join("; ") };
-  }
-  return { ok: true, config: merged.data };
-}
-
 export function loadConfig(): Config {
-  let fileData: z.infer<typeof ConfigFileSchema> = {};
+  let raw: unknown = {};
   if (existsSync(paths.configJson)) {
-    let raw: unknown;
     try {
       raw = JSON.parse(readFileSync(paths.configJson, "utf8"));
     } catch {
       throw new Error(`${paths.configJson} is corrupt (unparsable JSON) - fix or remove it`);
     }
-    const parsed = ConfigFileSchema.safeParse(raw);
-    if (!parsed.success) {
-      const fields = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
-      throw new Error(`${paths.configJson} has wrong-typed values (${fields}) - fix or remove them`);
-    }
-    fileData = parsed.data;
   }
-  const outcome = mergeConfigFile(fileData);
-  if (!outcome.ok) throw new Error(`${paths.configJson} is invalid: ${outcome.detail} - fix or remove the offending values`);
-  return outcome.config;
+  const parsed = ConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const fields = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
+    throw new Error(`${paths.configJson} is invalid (${fields}) - fix or remove the offending values`);
+  }
+  const cfg = parsed.data;
+  const envBin = realClaudeBinFromEnv();
+  if (envBin) cfg.claudeBin = envBin;
+  const envCodexBin = realCodexBinFromEnv();
+  if (envCodexBin) cfg.codexBin = envCodexBin;
+  return cfg;
 }
 
 export function pinBinOverride(input: { key: "claudeBin" | "codexBin"; bin: string }): void {

package/src/lib/types.ts

@@ -101,19 +101,30 @@ export type Thresholds = z.infer<typeof ThresholdsSchema>;
 
 export const ConfigSchema = z
   .object({
-    thresholds: ThresholdsSchema,
-    claudeBin: z.string(),
-    codexBin: z.string(),
-    policy: z.object({
-      projectionMargin: z.number().min(0).max(100),
-      switchModels: z.array(z.string()),
-      usagePollTtlMs: z.number().int().positive(),
-      maxWaitMs: z.number().int().positive(),
-      checkIntervalMs: z.number().int().min(10_000),
-    }),
+    thresholds: z
+      .object({
+        session: z.number().min(0).max(100).default(90),
+        weekly: z.number().min(0).max(100).default(98),
+      })
+      .prefault({}),
+    claudeBin: z.string().default(""),
+    codexBin: z.string().default(""),
+    policy: z
+      .object({
+        projectionMargin: z.number().min(0).max(100).default(0),
+        switchModels: z
+          .array(z.string())
+          .default(["fable"])
+          .transform((models) => models.map((model) => model.toLowerCase())),
+        usagePollTtlMs: z.number().int().positive().default(90_000),
+        maxWaitMs: z.number().int().positive().default(3_600_000),
+        checkIntervalMs: z.number().int().min(10_000).default(60_000),
+      })
+      .prefault({}),
   })
   .refine((cfg) => cfg.policy.projectionMargin < Math.min(cfg.thresholds.session, cfg.thresholds.weekly), {
-    message: "policy.projectionMargin must be strictly below both thresholds (the bars would hit zero and every account would read as exhausted)",
+    path: ["policy", "projectionMargin"],
+    message: "must be strictly below both thresholds (the bars would hit zero and every account would read as exhausted)",
   });
 export type Config = z.infer<typeof ConfigSchema>;
 

package/src/main.ts

@@ -46,7 +46,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing auth")} [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every needs-reauth account, one by one)
   ${c.cyan("tokenmaxxing switch --codex")} [sel]  switch the codex pool (takes effect on next codex start)
   ${c.cyan("tokenmaxxing status")} [--cached]  accounts with 5h / weekly / per-model usage bars (--cached: the stored figures, no sampling)
-  ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
+  ${c.cyan("tokenmaxxing config")}     print the config path and the effective values (edit the file in an editor)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex] <sel>