tokenmaxxing 1.10.0 → 1.12.0

package/DESIGN.md

@@ -1,6 +1,6 @@
 # tokenmaxxing - design
 
-Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (the active rung of the 5h session ladder, **50, then 80, then 95** as the pool fills, or **98%** of a weekly window), tokenmaxxing swaps the credential to a fresh account at a safe turn boundary and **your running session adopts it in place - no restart**. Works across many concurrent sessions at once; a fully depleted pool pauses with a countdown and auto-resumes at the soonest reset when it lands within `policy.maxWaitMs` (default 1h; further out, the session stays put rather than parking for hours).
+Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (the active rung of the 5h session ladder, **90** by default, or **98%** of a weekly window), tokenmaxxing swaps the credential to a fresh account at a safe turn boundary and **your running session adopts it in place - no restart**. Works across many concurrent sessions at once; a fully depleted pool pauses with a countdown and auto-resumes at the soonest reset when it lands within `policy.maxWaitMs` (default 1h; further out, 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, decision engine, and supervisor; its verified internals live in AGENTS.md's Codex sections.
 >
@@ -12,7 +12,7 @@ Automatic Claude Code account switching. You run `claude` exactly as always; whe
 
 A **running** `claude` DOES adopt an externally swapped credential (verified live 2026-07-10, correcting this document's original claim): an ensure-fresh poll re-reads the credential store around every request, so a swap lands within ~30s on macOS (raw keychain cache) and on the next request on Linux. A plain swap therefore needs no process management at all (since 0.15.0, 2026-07-16; earlier versions respawned on every swap): the Stop hook swaps the credential and the session keeps running. What adoption cannot give you is the depleted case: when every account is at the wall the session must be PAUSED until something resets, and a live `claude` cannot pause itself.
 
-So the supervisor's job is narrow: on a depleted pool it **replaces the process at a salvageable moment** - after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt, so killing it there loses nothing - shows an interruptible countdown to the soonest reset, and relaunches `claude --resume <session-id>` when it passes. **Thresholds still sit below 100%: the headroom is the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the account actually hits the wall.** The session window climbs a ladder, 50 then 80 then 95, each rung taking over once every pooled account is past the one below (a 5h reset is cheap to sit out, so the pool drains level by level), while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
+So the supervisor's job is narrow: on a depleted pool it **replaces the process at a salvageable moment** - after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt, so killing it there loses nothing - shows an interruptible countdown to the soonest reset, and relaunches `claude --resume <session-id>` when it passes. **Thresholds still sit below 100%: the headroom is the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the account actually hits the wall.** The session window screens on a ladder, a single rung at 90 by default; a configured ladder like 50 then 80 then 95 has each rung take over once every pooled account is past the one below (a 5h reset is cheap to sit out, so a multi-rung pool drains level by level), while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
 
 A hook can't do the pause-and-relaunch - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
 
@@ -49,7 +49,7 @@ The switching path runs no long-lived daemon. The statusline pushes usage. Hooks
 The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine tees that to `usage.json` (write-on-change, O(ms)) and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). Cold-start fallback if `usage.json` is absent: `TOKENMAXXING_PROBE=1 claude -p '/usage'`, with `[ -n "$TOKENMAXXING_PROBE" ] && exit 0` as the hook's first line to stop the nested process recursing (hooks fire in `-p` too). The probe scrubs every ambient credential override claude reads before the keychain (`CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, etc.) so it can only meter the credential in the keychain item, and retries the transient empty-footer case (claude prints local stats with no percentages when its own usage fetch throttles).
 
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
-1. Read `usage.json`; `exit 0` fast below the engagement floor (`policy.greedySessionFloor`, default 50% of the 5h window) unless a screening bar is already crossed. Engaged-but-under-every-bar runs the GREEDY convergence: stay when the current account wins or ties, else swap onto the strictly better account. A crossed bar forces the hard path (metered per `organizationUuid`).
+1. Read `usage.json`; `exit 0` fast below the engagement floor (`policy.greedySessionFloor`, default 80% of the 5h window) unless a screening bar is already crossed. Engaged-but-under-every-bar runs the GREEDY convergence: stay when the current account wins or ties, else swap onto the strictly better account. A crossed bar forces the hard path (metered per `organizationUuid`).
 2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (not rate-limited, furthest behind its own weekly pace first: highest remaining% / time-to-weekly-reset, since unused allowance is forfeited at the fixed per-account reset; tiebreak soonest expiry then lowest 7-day usage), and **swap the credential** (§3.4).
 3. Done - the running session adopts the new credential on its own within a request or two. Only when the pool is depleted (the decision returned a `waitUntil`: pre-parked on the soonest-recovering account, or staying on the current one when it recovers first) does the hook write `respawn/<session_id>` (atomic temp+rename).
 
@@ -79,7 +79,7 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 ---
 
 ## 5. Rotation policy
-The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from there it greedily converges on the usable account furthest behind its weekly pace, staying put whenever the current account wins or ties. The **Layer 1 screening bars** - `five_hour >= <active rung>` (the 5h ladder `thresholds.session`, default 50/80/95: the lowest rung some pooled account still clears, the current one included) OR `seven_day >= 98%`, per org (`thresholds`) - force a switch onto a fresher account and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - policy.projectionMargin`, a fixed configured margin) so a single large turn is less likely to blow past 100% before the next Stop hook.
+The decision engages at `five_hour >= 80%` (policy.greedySessionFloor): from there it greedily converges on the usable account furthest behind its weekly pace, staying put whenever the current account wins or ties. The **Layer 1 screening bars** - `five_hour >= <active rung>` (the 5h ladder `thresholds.session`, default `[90]`, a single rung: the lowest rung some pooled account still clears, the current one included) OR `seven_day >= 98%`, per org (`thresholds`) - force a switch onto a fresher account and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - policy.projectionMargin`, a fixed configured margin) so a single large turn is less likely to blow past 100% before the next Stop hook.
 
 **Two layers - pump the last drops.** The screening bars deliberately leave headroom, so when *every* account is over them Layer 1 alone would park the pool with 2-5% of each account's quota still unspent. **Layer 2 - the wall bars** (`hardThresholds`, default `100/100`, the server's own limit) - is the fallback reached only at that point: the session **holds its seat and squeezes** while it is under the wall, else swaps onto the best still-under-wall account (the same pace-pressure ranking as every other swap - squeeze the account whose weekly quota is most about to be forfeited first), and only parks (depleted-wait) once every account has truly walled. Recovery is then measured against the wall, not the screening bar, so an account whose 5h window drops below 100 is squeezable again even while its weekly window still sits above the Layer 1 bar. The wall reading is the statusLine's own `rate_limits` feed - the same server-side figure claude's `/rate-limit-options` renders - so when an account genuinely maxes out the tee shows 100 and Layer 2 moves on; a single-turn overshoot is caught one boundary later (the periodic `check` timer, or the next Stop hook) without needing to sniff assistant text. Set `hardThresholds` equal to `thresholds` to disable Layer 2. **Layer 2 is Claude-only:** a swap on Claude is a hot, in-place credential adoption every concurrent session follows automatically, whereas a running Codex refuses another account's credential (restart is the switch), so a last-drop-swap there would strand any sibling still on the walled account - Codex instead keeps riding its current account to the wall (its existing all-exhausted stay-put already squeezes it).
 

package/README.md

@@ -76,15 +76,16 @@ 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
 
-Switching engages (configurable) once the active account's 5-hour session window is **50% used** - from there, every evaluation greedily converges on the usable account **furthest behind its own weekly pace**, and does nothing when the current account already wins. Independent of that, crossing a screening bar always forces a switch: the session bar is the active rung of a ladder (**50**, then **80**, then **95**, each rung taking over once every pooled account is past the one below) and the weekly bar is **98%**. The bars also screen candidates on any of:
+Switching engages (configurable) once the active account's 5-hour session window is **80% used** - from there, every evaluation greedily converges on the usable account **furthest behind its own weekly pace**, and does nothing when the current account already wins. Independent of that, crossing a screening bar always forces a switch: the session bar is the active rung of a ladder (a single rung at **90** by default; with more rungs configured, each takes over once every pooled account is past the one below) and the weekly bar is **98%**. The bars also screen candidates on any of:
 
 - **Session** (5-hour) or **week (all models)** - the aggregate windows, fed free/push-based by the statusLine.
 - **Per-model weekly cap** - the most capable model (Fable) has its own tighter weekly limit that binds *before* the aggregate (per-model caps currently exist only for Sonnet and Fable, and Sonnet's is generous). tokenmaxxing reads it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) whenever the active model is one of `policy.switchModels`, so a Fable session switches on the Fable cap while a Sonnet session rides the aggregate.
 
-The bars' headroom is deliberate: it's the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the wall. The session ladder tops out lower (95) because a 5-hour reset is cheap to sit out, and its lower rungs keep the pool draining level by level; weekly quota is use-it-or-lose-it, so it drains closer to the wall (98). The greedy engagement floor sits far below both: weekly allowance is forfeited at each account's fixed reset, so once half a session window justifies the swap, quota is best burned on whichever account has the most at risk.
+The bars' headroom is deliberate: it's the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the wall. The session ladder tops out lower (90) because a 5-hour reset is cheap to sit out, and any lower rungs you add keep the pool draining level by level; weekly quota is use-it-or-lose-it, so it drains closer to the wall (98). The greedy engagement floor (80) sits below both: weekly allowance is forfeited at each account's fixed reset, so once most of a session window is spent, quota is best burned on whichever account has the most at risk.
 
 The **target** is chosen greedily off each account's cached windows: among usable accounts (every window under its bar, or past its reset), the one **furthest behind its own weekly pace** - highest remaining% divided by time to its weekly reset - because unused weekly allowance is forfeited at the fixed per-account reset. Cached resets are absolute UTC epochs, so a stale snapshot still resolves correctly: a weekly reset that has passed extrapolates forward in 7-day steps, and a session window past its reset counts as empty. Both `tokenmaxxing switch` and the automatic path rank the current account too and do nothing when it already wins, so they are idempotent - evaluating periodically converges on the right account.
 
@@ -94,17 +95,17 @@ The **target** is chosen greedily off each account's cached windows: among usabl
 
 ```json
 {
-  "thresholds": { "session": [50, 80, 95], "weekly": 98 },
+  "thresholds": { "session": [90], "weekly": 98 },
   "policy": {
     "projectionMargin": 0,
-    "greedySessionFloor": 50,
+    "greedySessionFloor": 80,
     "switchModels": ["fable"],
     "usagePollTtlMs": 90000
   }
 }
 ```
 
-`thresholds.session` is a ladder: the bar is the lowest rung some pooled account still clears, so a seat past 50 hands off while a sibling is under 50, and the bar climbs to 80 and then 95 as the whole pool fills; `projectionMargin` is a fixed safety margin subtracted from each threshold bar (effective bar = threshold - margin), so a large turn is less likely to blow past a bar between checks; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers).
+`thresholds.session` is a ladder: the bar is the lowest rung some pooled account still clears, so the default `[90]` is one bar, while with `[50, 80, 95]` a seat past 50 hands off while a sibling is under 50, and the bar climbs to 80 and then 95 as the whole pool fills; `projectionMargin` is a fixed safety margin subtracted from each threshold bar (effective bar = threshold - margin), so a large turn is less likely to blow past a bar between checks; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers).
 
 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`).
 

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.12.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/agent-plugin/skills/switching-policy/SKILL.md

@@ -7,11 +7,11 @@ description: Explain and apply tokenmaxxing switch policy (greedy vs hard path,
 
 ## Vocabulary
 
-- **Engaged**: session used >= `policy.greedySessionFloor` (default 50) or any screening bar crossed.
+- **Engaged**: session used >= `policy.greedySessionFloor` (default 80) or any screening bar crossed.
 - **GREEDY path**: engaged but under every bar. Rank all accounts by pace pressure; keep seat on best-or-tie (`currentWins`); else swap to strictly better. Never depleted-waits or pre-parks.
 - **HARD path**: a screening bar crossed. Swap to best usable target; if none, Layer 2 wall logic (Claude only).
 - **Pace pressure**: remaining weekly percent / time to weekly reset (highest first). Not most-remaining.
-- **Effective bars**: `effectiveBars(cfg, pool)` = the active rung of the 5h ladder (`thresholds.session`, default 50/80/95: the lowest rung some pooled account, the current one included, still clears) and the weekly bar, each minus `policy.projectionMargin`. Trigger and screening must share these bars or swaps ping-pong. Codex reads `terminalBars(cfg)`, the top rung only. The check cadence is capped one band per rung climbed.
+- **Effective bars**: `effectiveBars(cfg, pool)` = the active rung of the 5h ladder (`thresholds.session`, default `[90]`, a single rung: the lowest rung some pooled account, the current one included, still clears) and the weekly bar, each minus `policy.projectionMargin`. Trigger and screening must share these bars or swaps ping-pong. Codex reads `terminalBars(cfg)`, the top rung only. The check cadence is capped one band per rung climbed.
 
 ## Layer 2 (Claude only)
 

package/agent-plugin/skills/switching-policy/references/policy.md

@@ -4,4 +4,4 @@
 - `src/lib/decide.ts`, `src/lib/picker.ts`
 - `.memory/switch-policy-pace-pressure.md`
 
-Default screening bars: session ladder [50, 80, 95] with the active rung resolved per pool, weekly 98. Wall defaults 100. Cooldown 45s on the automatic path after a swap. Check cadence ceiling per rung: 300s, 180s, 120s, then the 60s floor.
+Default screening bars: session ladder [90] (a single rung; add lower rungs such as [50, 80, 95] to hand off earlier) with the active rung resolved per pool, weekly 98. Engagement floor 80. Wall defaults 100. Cooldown 45s on the automatic path after a swap. Check cadence ceiling per rung: 300s, 180s, 120s, then the 60s floor.

package/package.json

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

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;
 }