tokenmaxxing 1.10.0 → 1.11.0

package/README.md

@@ -76,6 +76,7 @@ claude                  # use claude as always
 | `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) |
+| `--json` | machine-readable output: one JSON document on stdout for `status`, `ls`, `config`, `doctor`, `check`, `switch`, `rename`, `rm`, `uninstall`, and one per tick for `watch` (`ok` mirrors the exit code, failures add `error`) |
 
 ## How switching decides
 

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tokenmaxxing",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Pool Claude Code and Codex logins, switch on pace pressure, and expose safe ops tools to agent clients.",
   "author": {
     "name": "anaclumos",

package/agent-plugin/skills/pool-status/SKILL.md

@@ -10,7 +10,7 @@ description: Read the Claude and Codex account pool safely (list, usage bars, wa
 - `pool_ls` for labels, active marker, needs-reauth
 - `pool_status` for 5h / weekly / per-model bars (free `/usage` path)
 
-If MCP is unavailable, run `tokenmaxxing ls` or `tokenmaxxing status` (alias `xx`). Never add `--force`.
+If MCP is unavailable, run `tokenmaxxing ls --json` or `tokenmaxxing status --json` (alias `xx`) and parse the document. Never add `--force`.
 
 ## Hard stops
 
@@ -22,6 +22,6 @@ If MCP is unavailable, run `tokenmaxxing ls` or `tokenmaxxing status` (alias `xx
 
 - Active Claude usage often comes from the statusLine tee; parked accounts are probed in isolation.
 - `watch` re-renders status on an interval and never force-pings.
-- Hermetic agents: set `TOKENMAXXING_HOME` to a throwaway directory.
+- Hermetic agents: set `TOKENMAXXING_HOME` to a throwaway directory. That isolates state files only: `init`, `uninstall`, and the codex hook install still write settings.json, codex `hooks.json`, the shell rc, and the timer unit under `HOME`, so never run them from an agent.
 
 See [references/commands.md](references/commands.md).

package/agent-plugin/skills/pool-status/references/commands.md

@@ -4,5 +4,6 @@
 - `tokenmaxxing status --force`: DENIED for agents without explicit user approval. Meters every account.
 - `tokenmaxxing ls`: compact list.
 - `tokenmaxxing watch [seconds]`: live re-render (default 120), never `--force`.
+- `--json` on any of these: one JSON document on stdout (`ok` mirrors the exit code); parse it instead of scraping the bars. `watch --json` prints one document per tick and never exits on its own.
 
 Docs: `docs/content/docs/commands.mdx`.

package/package.json

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

@@ -2,15 +2,16 @@ import { CHECK_DELAY_FLOOR_MS, checkDelayMs, evaluateAndMaybeSwap } from "../lib
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { log } from "../lib/log.ts";
 import { loadConfig, loadNextCheckDueAt, saveNextCheckDueAt } from "../lib/state.ts";
-import { c, fmtReset } from "./render.ts";
+import { c, emitError, emitJson, fmtReset } from "./render.ts";
 
 const TICK_SLACK_MS = CHECK_DELAY_FLOOR_MS / 2;
 
-export async function cmdCheck(args: string[] = []): Promise<number> {
+export async function cmdCheck(args: string[] = [], json = false): Promise<number> {
   const now = Date.now();
   const dueAt = args.includes("--if-due") ? loadNextCheckDueAt(now) : null;
   if (dueAt != null && now + TICK_SLACK_MS < dueAt) {
-    console.log(c.dim(`not due (${Math.ceil((dueAt - now) / 1000)}s)`));
+    if (json) emitJson({ ok: true, due: false, nextCheckAt: dueAt });
+    else console.log(c.dim(`not due (${Math.ceil((dueAt - now) / 1000)}s)`));
     return 0;
   }
   let d;
@@ -19,11 +20,23 @@ export async function cmdCheck(args: string[] = []): Promise<number> {
   } catch (e) {
     const detail = e instanceof Error ? e.message : String(e);
     log("check.error", { err: detail });
-    console.error(c.red(`check failed: ${detail}`));
+    emitError({ json, message: `check failed: ${detail}` });
     return 1;
   }
   const delayMs = checkDelayMs({ cfg: loadConfig(), org: readOAuthAccount()?.organizationUuid ?? null, now, decision: d });
   saveNextCheckDueAt({ dueAt: now + delayMs, ts: now });
+  if (json) {
+    emitJson({
+      ok: true,
+      due: true,
+      swapped: d.swapped,
+      account: d.account?.label ?? null,
+      reason: d.reason,
+      waitUntil: d.waitUntil ?? null,
+      nextCheckAt: now + delayMs,
+    });
+    return 0;
+  }
   const next = c.dim(`next in ${Math.round(delayMs / 1000)}s`);
   if (d.swapped && d.account) {
     console.log(`${c.green("↻")} switched to ${c.bold(d.account.label)} ${next}`);

package/src/cli/codexrm.ts

@@ -5,32 +5,33 @@ import { deleteParkedCodexAuth } from "../lib/codexauth.ts";
 import { liveCodexAccountId } from "../lib/codexsample.ts";
 import { presentCodexAccountIds } from "../lib/codexpresence.ts";
 import { findCodexAccount } from "./rename.ts";
-import { c } from "./render.ts";
+import { c, emitError, emitJson, plain } from "./render.ts";
 
-export async function cmdCodexRm(selector?: string): Promise<number> {
+export async function cmdCodexRm(selector?: string, json = false): Promise<number> {
   if (!selector) {
-    console.error("usage: tokenmaxxing rm --codex <email|label|id>");
+    emitError({ json, message: "usage: tokenmaxxing rm --codex <email|label|id>", paint: plain });
     return 2;
   }
   return withLock(codexPaths.lockFile, async () => {
     const index = loadCodexAccounts();
     const account = findCodexAccount(index.accounts, selector);
     if (!account) {
-      console.error(c.red(`no codex account matches "${selector}"`));
+      emitError({ json, message: `no codex account matches "${selector}"` });
       return 1;
     }
     if (liveCodexAccountId() === account.accountId) {
-      console.error(c.red(`${account.label} is the LIVE codex account - run \`tokenmaxxing switch --codex\` to move off it first.`));
+      emitError({ json, message: `${account.label} is the LIVE codex account - run \`tokenmaxxing switch --codex\` to move off it first.` });
       return 1;
     }
     if (presentCodexAccountIds().has(account.accountId)) {
-      console.error(c.red(`${account.label} is running in a live codex session - close that session before removing it.`));
+      emitError({ json, message: `${account.label} is running in a live codex session - close that session before removing it.` });
       return 1;
     }
     deleteParkedCodexAuth({ credFile: account.credFile });
     index.accounts = index.accounts.filter((x) => x.accountId !== account.accountId);
     saveCodexAccounts({ index });
-    console.log(`removed codex account ${c.bold(account.label)} from the pool (${index.accounts.length} left)`);
+    if (json) emitJson({ ok: true, pool: "codex", removed: account.label, remaining: index.accounts.length });
+    else console.log(`removed codex account ${c.bold(account.label)} from the pool (${index.accounts.length} left)`);
     return 0;
   });
 }

package/src/cli/codexswitch.ts

@@ -8,9 +8,20 @@ import { CodexInvalidGrantError } from "../lib/codexoauth.ts";
 import { liveCodexAccountId } from "../lib/codexsample.ts";
 import { presentCodexAccountIds, targetableCodexAccounts } from "../lib/codexpresence.ts";
 import { terminalBars } from "../lib/picker.ts";
-import { c } from "./render.ts";
+import { c, emitError, emitJson } from "./render.ts";
 
-export async function cmdCodexSwitch(sel?: string): Promise<number> {
+export async function cmdCodexSwitch(sel?: string, json = false): Promise<number> {
+  const deadGrants: string[] = [];
+  const withDeadGrants = (report: Record<string, unknown>) => (deadGrants.length > 0 ? { ...report, deadGrants } : report);
+  const emit = (text: string, report: Record<string, unknown>): void => {
+    if (json) emitJson({ ok: true, ...withDeadGrants(report) });
+    else console.log(text);
+  };
+  const fail = (message: string, opts: { paint?: (s: string) => string; notes?: string[]; extra?: Record<string, unknown> } = {}): number => {
+    emitError({ json, message, paint: opts.paint, notes: opts.notes, extra: withDeadGrants(opts.extra ?? {}) });
+    return 1;
+  };
+  const deadGrantMessage = (label: string) => `${label}'s refresh token is dead - re-add it with \`tokenmaxxing add --codex\``;
   const cfg = loadConfig();
   const bars = terminalBars(cfg);
   const now = Date.now();
@@ -18,7 +29,8 @@ export async function cmdCodexSwitch(sel?: string): Promise<number> {
   return withLock(codexPaths.lockFile, async () => {
     const index = loadCodexAccounts();
     if (index.accounts.length === 0) {
-      console.log(c.dim("no codex accounts yet - run `tokenmaxxing init --codex`"));
+      if (json) emitJson({ ok: false, error: "no codex accounts yet - run `tokenmaxxing init --codex`" });
+      else console.log(c.dim("no codex accounts yet - run `tokenmaxxing init --codex`"));
       return 1;
     }
     const currentId = liveCodexAccountId();
@@ -28,32 +40,35 @@ export async function cmdCodexSwitch(sel?: string): Promise<number> {
         (account) => account.label === sel || account.email === sel || account.accountId.startsWith(sel),
       );
       if (!target) {
-        console.error(c.red(`no codex account matches "${sel}"`));
-        for (const account of index.accounts) console.error(c.dim(`  ${account.label} (${account.accountId.slice(0, 8)})`));
-        return 1;
+        return fail(`no codex account matches "${sel}"`, {
+          notes: index.accounts.map((account) => `  ${account.label} (${account.accountId.slice(0, 8)})`),
+          extra: { accounts: index.accounts.map((account) => account.label) },
+        });
       }
       if (target.accountId === currentId) {
-        console.log(`already on ${c.bold(target.label)}`);
+        emit(`already on ${c.bold(target.label)}`, { switched: false, account: target.label, reason: "already-on" });
         return 0;
       }
       if (presentCodexAccountIds().has(target.accountId)) {
-        console.error(c.red(`${target.label} is running in a live codex session - swapping onto it would break that session's credential`));
-        return 1;
+        return fail(`${target.label} is running in a live codex session - swapping onto it would break that session's credential`);
       }
       if (target.needsReauth) {
-        console.error(c.red(`${target.label} needs re-auth - run \`codex login\` in an isolated home and \`tokenmaxxing add --codex\``));
-        return 1;
+        return fail(`${target.label} needs re-auth - run \`codex login\` in an isolated home and \`tokenmaxxing add --codex\``);
       }
       try {
         await performCodexSwap({ target });
       } catch (e) {
         if (e instanceof CodexInvalidGrantError) {
-          console.error(c.red(`${target.label}'s refresh token is dead - re-add it with \`tokenmaxxing add --codex\``));
-          return 1;
+          deadGrants.push(target.label);
+          return fail(deadGrantMessage(target.label));
         }
         throw e;
       }
-      console.log(`${c.green("✓")} switched codex to ${c.bold(target.label)} (takes effect on the next codex start)`);
+      emit(`${c.green("✓")} switched codex to ${c.bold(target.label)} (takes effect on the next codex start)`, {
+        switched: true,
+        account: target.label,
+        reason: "selected",
+      });
       return 0;
     }
 
@@ -62,21 +77,36 @@ export async function cmdCodexSwitch(sel?: string): Promise<number> {
       const candidates = targetableCodexAccounts({ accounts: current.accounts, activeAccountId: currentId });
       const active = candidates.find((account) => account.accountId === currentId) ?? null;
       if (codexCurrentWins({ active, accounts: candidates, thresholds: bars, now })) {
-        console.log(`already on the best codex account: ${c.bold(active?.label ?? "?")}`);
+        emit(`already on the best codex account: ${c.bold(active?.label ?? "?")}`, {
+          switched: false,
+          account: active?.label ?? null,
+          reason: "current-wins",
+        });
         return 0;
       }
       const best = pickBestCodex({ accounts: candidates, thresholds: bars, now, currentAccountId: currentId });
       if (!best) {
-        console.log(c.yellow("no usable codex switch target (all at their bars, unmeasured, or needing reauth)"));
+        const message = "no usable codex switch target (all at their bars, unmeasured, or needing reauth)";
+        const reauthNeeded = current.accounts.filter((account) => account.needsReauth).map((account) => account.label);
+        if (json) return fail(message, { extra: { reauthNeeded } });
+        console.log(c.yellow(message));
         return 1;
       }
       try {
         await performCodexSwap({ target: best });
       } catch (e) {
-        if (e instanceof CodexInvalidGrantError) continue;
+        if (e instanceof CodexInvalidGrantError) {
+          deadGrants.push(best.label);
+          if (!json) console.error(c.red(deadGrantMessage(best.label)));
+          continue;
+        }
         throw e;
       }
-      console.log(`${c.green("✓")} switched codex to ${c.bold(best.label)} (takes effect on the next codex start)`);
+      emit(`${c.green("✓")} switched codex to ${c.bold(best.label)} (takes effect on the next codex start)`, {
+        switched: true,
+        account: best.label,
+        reason: "best",
+      });
       return 0;
     }
   });

package/src/cli/config.ts

@@ -5,7 +5,7 @@ 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 { c } from "./render.ts";
+import { c, emitError, emitJson } from "./render.ts";
 
 export const KNOWN_KEYS = [
   "thresholds.session",
@@ -49,22 +49,53 @@ function unknownFileKeys(raw: Record<string, unknown>): string[] {
   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 printEffective(): number {
+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 env = envSourceFor(key);
-    const source = env ? c.yellow(`env ${env}`) : get(raw, key) !== undefined ? c.green("file") : c.dim("default");
-    console.log(`  ${key.padEnd(28)} ${JSON.stringify(get(effective, key))}  ${source}`);
+    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}`);
   }
-  const unknown = unknownFileKeys(raw);
   if (unknown.length > 0) {
     console.log();
     console.log(c.yellow(`unknown keys in the file (ignored by the loader): ${unknown.join(", ")}`));
@@ -73,13 +104,14 @@ function printEffective(): number {
   return 0;
 }
 
-function cmdGet(key: string): number {
-  if (!KNOWN_KEYS.some((known) => known === key)) {
-    console.error(c.red(`unknown config key: ${key}`));
-    console.error(c.dim(`known keys: ${KNOWN_KEYS.join(", ")}`));
-    return 1;
+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;
   }
-  console.log(JSON.stringify(get(loadConfig(), key)));
+  console.log(JSON.stringify(value));
   return 0;
 }
 
@@ -91,31 +123,31 @@ function parseValue(text: string): unknown {
   }
 }
 
-function cmdSet(key: string, valueText: string): number {
-  if (!KNOWN_KEYS.some((known) => known === key)) {
-    console.error(c.red(`unknown config key: ${key}`));
-    console.error(c.dim(`known keys: ${KNOWN_KEYS.join(", ")}`));
-    return 1;
-  }
+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) {
-    console.error(c.red(`rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`));
+    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) {
-    console.error(c.red(`rejected: ${mergedCheck.detail}`));
+    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))}`,
   );
-  const env = envSourceFor(key);
   if (env) console.log(c.yellow(`note: ${env} is set and overrides the file value in this environment`));
   return 0;
 }
@@ -128,14 +160,12 @@ function pruneEmptyParents(raw: Record<string, unknown>): void {
   }
 }
 
-function cmdUnset(key: string): number {
-  if (!KNOWN_KEYS.some((known) => known === key)) {
-    console.error(c.red(`unknown config key: ${key}`));
-    return 1;
-  }
+function cmdUnset(key: string, json: boolean): number {
+  if (!isKnownKey(key)) return unknownKey({ key, json });
   const raw = readRawFile();
   if (get(raw, key) === undefined) {
-    console.log(c.dim(`${key} has no file override (default already applies)`));
+    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);
@@ -143,20 +173,25 @@ function cmdUnset(key: string): number {
   pruneEmptyParents(next);
   const validated = ConfigFileSchema.safeParse(next);
   if (!validated.success) {
-    console.error(c.red(`rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`));
+    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) {
-    console.error(c.red(`rejected: ${mergedCheck.detail} (adjust the conflicting override before unsetting ${key})`));
+    emitError({ json, message: `rejected: ${mergedCheck.detail} (adjust the conflicting override before unsetting ${key})` });
     return 1;
   }
   writeRawFile({ raw: next });
-  console.log(`${key} unset -> ${JSON.stringify(get(loadConfig(), key))} (default)`);
+  const value = get(loadConfig(), key);
+  if (json) {
+    emitJson({ ok: true, key, unset: true, value });
+    return 0;
+  }
+  console.log(`${key} unset -> ${JSON.stringify(value)} (default)`);
   return 0;
 }
 
-function cmdTidy(): number {
+function cmdTidy(json: boolean): number {
   const raw = readRawFile();
   const dropped = unknownFileKeys(raw);
   const parsed = ConfigFileSchema.parse(raw);
@@ -167,30 +202,39 @@ function cmdTidy(): number {
   if (normalized != null) set(next, "policy.switchModels", normalized);
   pruneEmptyParents(next);
 
-  if (JSON.stringify(next) === JSON.stringify(raw)) {
+  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"));
     return 0;
   }
-  writeRawFile({ raw: next });
   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)");
   return 0;
 }
 
-export function cmdConfig(args: string[]): number {
+export function cmdConfig(args: string[], json = false): number {
   const [sub, key, value] = args;
   try {
-    if (sub === undefined) return printEffective();
-    if (sub === "get" && key !== undefined) return cmdGet(key);
-    if (sub === "set" && key !== undefined && value !== undefined) return cmdSet(key, value);
-    if (sub === "unset" && key !== undefined) return cmdUnset(key);
-    if (sub === "tidy") return cmdTidy();
+    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) {
-    console.error(c.red(`config.json is unreadable: ${e instanceof Error ? e.message : String(e)}`));
-    console.error(c.dim(`fix or delete ${paths.configJson} (defaults apply when it is absent), then re-run`));
+    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;
   }
-  console.error(c.red("usage: tokenmaxxing config [get <key> | set <key> <value> | unset <key> | tidy]"));
+  emitError({ json, message: "usage: tokenmaxxing config [get <key> | set <key> <value> | unset <key> | tidy]" });
   return 2;
 }

package/src/cli/doctor.ts

@@ -7,7 +7,7 @@ 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";
+import { c, emitJson } from "./render.ts";
 
 async function blobOrg(raw: string): Promise<RolesResponse | null> {
   const creds = CredentialBlobSchema.parse(JSON.parse(raw)).claudeAiOauth;
@@ -15,11 +15,21 @@ async function blobOrg(raw: string): Promise<RolesResponse | null> {
   return fetchTokenOrg(creds.accessToken);
 }
 
-export async function cmdDoctor(): Promise<number> {
-  let ok = true;
+export async function cmdDoctor(json = false): Promise<number> {
+  const checks: { ok: boolean; label: string; hint: string | null }[] = [];
+  const notes: string[] = [];
+  const warnings: string[] = [];
   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;
+    checks.push({ ok: cond, label, hint: cond ? null : (hint ?? null) });
+    if (!json) console.log(`${cond ? c.green("✓") : c.red("✗")} ${label}${!cond && hint ? c.dim(`  - ${hint}`) : ""}`);
+  };
+  const note = (text: string) => {
+    notes.push(text);
+    if (!json) console.log(c.dim(`  - ${text}`));
+  };
+  const warn = (text: string) => {
+    warnings.push(text);
+    if (!json) console.log(c.yellow(`⚠ ${text}`));
   };
 
   check(existsSync(paths.supervisorLink), "claude supervisor wrapper present", "run `tokenmaxxing init`");
@@ -46,7 +56,7 @@ export async function cmdDoctor(): Promise<number> {
     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)`));
+      else note("live credential identity unverifiable (access token expired)");
     } catch (e) {
       check(false, `live credential identity matches active (${active.email})`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
     }
@@ -59,7 +69,7 @@ export async function cmdDoctor(): Promise<number> {
       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} - run \`tokenmaxxing auth ${a.label}\``);
-        else console.log(c.dim(`  - ${a.email} identity unverifiable (access token expired)`));
+        else note(`${a.email} identity unverifiable (access token expired)`);
       } catch (e) {
         check(false, `parked credential identity matches ${a.email}`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
       }
@@ -77,11 +87,17 @@ export async function cmdDoctor(): Promise<number> {
   const rc = shellRcPath();
   if (rc && existsSync(rc)) {
     for (const s of findClaudeShadowers(readFileSync(rc, "utf8"))) {
-      if (s.kind === "shadow") console.log(c.yellow(`⚠ ${rc}: \`${s.line}\` shadows the supervised claude wrapper - launches through it skip tokenmaxxing`));
-      else console.log(c.yellow(`⚠ ${rc}: alias \`${s.name}\` hardcodes a claude path and bypasses the supervisor - use plain \`claude\` in its body instead`));
+      if (s.kind === "shadow") warn(`${rc}: ${s.line.startsWith("alias ") ? "alias" : "function"} \`claude\` shadows the supervised claude wrapper - launches through it skip tokenmaxxing`);
+      else warn(`${rc}: alias \`${s.name}\` hardcodes a claude path and bypasses the supervisor - use plain \`claude\` in its body instead`);
     }
   }
 
+  const failed = checks.filter((entry) => !entry.ok).length;
+  const ok = failed === 0;
+  if (json) {
+    emitJson(ok ? { ok, checks, notes, warnings } : { ok, error: `issues found - ${failed} of ${checks.length} checks failed`, checks, notes, warnings });
+    return ok ? 0 : 1;
+  }
   console.log();
   console.log(ok ? c.green("all good ✓") : c.yellow("issues found - see above"));
   return ok ? 0 : 1;

package/src/cli/ls.ts

@@ -1,10 +1,45 @@
 import { loadAccounts } from "../lib/state.ts";
 import { loadCodexAccounts } from "../lib/codexstate.ts";
 import { liveCodexAccountId } from "../lib/codexsample.ts";
-import { c, claudeTierLabel } from "./render.ts";
+import { c, claudeTierLabel, emitJson } from "./render.ts";
 
-export function cmdLs(): number {
+export function cmdLs(json = false): number {
   const idx = loadAccounts();
+
+  if (json) {
+    const codex = loadCodexAccounts();
+    const liveId = codex.accounts.length > 0 ? liveCodexAccountId() : null;
+    emitJson({
+      ok: true,
+      claude: {
+        activeAccountUuid: idx.activeAccountUuid,
+        accounts: idx.accounts.map((a) => ({
+          label: a.label,
+          email: a.email,
+          accountUuid: a.accountUuid,
+          organizationUuid: a.organizationUuid,
+          tier: claudeTierLabel(a),
+          active: a.accountUuid === idx.activeAccountUuid,
+          needsReauth: a.needsReauth === true,
+          addedAt: a.addedAt,
+        })),
+      },
+      codex: {
+        activeAccountId: liveId,
+        accounts: codex.accounts.map((account) => ({
+          label: account.label,
+          email: account.email,
+          accountId: account.accountId,
+          planType: account.planType,
+          active: account.accountId === liveId,
+          needsReauth: account.needsReauth === true,
+          addedAt: account.addedAt,
+        })),
+      },
+    });
+    return 0;
+  }
+
   if (idx.accounts.length === 0) {
     console.log(c.dim("no accounts yet - run `tokenmaxxing init` then `tokenmaxxing add`"));
   }