Commands

Every command works inside a supervised session too: a CLAUDE_SECURESTORAGE_CONFIG_DIR inherited from the session is how the hooks know their seat, and the CLI accepts it.

JSON output

Add --json to status, config, or check and it prints one JSON document on stdout instead of text. The progress notice sampling claude usage... goes to stderr, so xx status --json | jq stays clean. status writes it only when stderr is a terminal, shows it while the sample runs, and erases it when the sample returns; a redirected stderr gets nothing. Every document carries ok, which is true exactly when the exit code is 0; a failure keeps its non-zero exit code and adds error with the same message the text form prints.

xx status --json | jq '.claude.accounts[] | {label, sessions, exhausted, fiveHour: .usage.fiveHour.usedPercentage}'
xx check --json | jq '{swapped, account, reason}'

What each command reports:

• status / bare xx: now (the reference time in epoch ms), then claude, codex, and grok, one object per pool with the same shape: thresholds, the effective bars and projectionMargin, gatedNote (a string when every account's gated per-model cap is at the weekly bar but at least one account still has weekly aggregate headroom for other models, else null), and one entry per account with id, label, email, tier, active, sessions, needsReauth, exhausted, thresholds (the account's thresholds.accounts entry, or null), usage, usageAt, limitsAt, and sample ({ok, source} for a fresh read from the statusline tee or a probe, {ok: true, source: "cached"} for a Claude account whose last sample attempt is inside its sample interval, {ok: false, reason} when the live sample failed and usage is the cached value from usageAt). sessions counts the supervised sessions and the seat borrowers on the account (on a Claude account, including a session that is moving to it or waiting for its reset), and active is true when that count is positive. usage is {fiveHour, week, limits}: the session window and the weekly window, classified by duration and each null when the plan has none, plus limits, one entry per named window (a Claude per-model cap or a Codex additional limit) with its name. Every window carries usedPercentage, bufferedPercentage, resetsAt, and windowSeconds, normalized the way the bars are drawn: a passed reset reads as 0 with the weekly reset rolled forward. usedPercentage is the provider's figure; bufferedPercentage is the buffered usage quota described below, and it is the figure the text form draws. The status-only grok pool is always present, with an empty accounts array when nothing is pooled. grok accounts carry the weekly credit window when a sample has landed (sessions is 0), and grok sample reports the credits billing read. status --cached (also xx --cached) reads only the state files: every sample is {ok: true, source: "cached"}, usage is the stored value as of usageAt (null when the account was never sampled), and limitsAt dates the named windows separately. When at least one API key is stored, the document also carries apiKeys, one entry per key with label, id, workspaceId (or null), creditUsd (the entered balance, or null), spentUsd, creditLeftUsd (creditUsd minus spentUsd, or null when no balance was entered), refused, refusedAt (epoch ms, or null), and sessions (the supervised sessions running on the key). With no key stored, the key is absent. The text form lists the keys after the Claude pool.
• config: path and effective (the config as loaded: file values over defaults, with TOKENMAXXING_CLAUDE_BIN, TOKENMAXXING_CODEX_BIN, TOKENMAXXING_GROK_BIN, and TOKENMAXXING_PI_BIN applied on top). A file that fails to load exits 1 with the zod message naming the field.
• check: swapped, account, reason, and waitUntil. A tick runs from no session, so swapped is false and reason is under-threshold-or-stale; the sampling it does is reported in the log.

Buffered usage quota: the usage bars of status, its bufferedPercentage fields, and the usage note add and auth print are measured against each account's switch threshold, not against the provider's full limit. The threshold is the account's own entry in thresholds.accounts, else the global threshold, minus policy.projectionMargin for the session window, and it is lifted near a reset the way switching lifts it (policy.accountReleaseMs). 100 means the account reached its switch threshold, where tokenmaxxing stops placing sessions on it unless its thresholds.accounts entry sets credits, and usage past that point stays at 100. The figure therefore reads higher than the usage Claude Code or Codex reports: an account with a threshold of 75 at 75 percent provider usage reads 100. The text form of status states this under the Claude and Codex pool headers. usedPercentage keeps the provider's figure. The status-only grok pool has no switch threshold, so its bufferedPercentage equals its usedPercentage.

Every other command refuses --json with exit code 2. Account identifiers (labels, emails, ids) appear in the documents; credential material never does.

--codex selects the Codex pool for init, add, auth, rm, rename, and seat; --grok selects the status-only grok pool for the same first five commands. The flags are mutually exclusive, and every other command refuses them with exit code 2 (status always renders every pool). --pi applies to init (with no pool flag) and to auth (alone for the Claude pool, with --codex for the Codex pool); every other command refuses it with exit code 2. Messages name accounts by label, which defaults to the sign-in email.