tokenmaxxing 1.174.0 → 1.176.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Automatic Claude Code account switching.** Run `claude` exactly as you always do; each session starts on the pooled account with room for it whose weekly quota is closest to expiring unused, and when that account nears its usage limit, tokenmaxxing resumes the session on a fresher account at a safe turn boundary - same conversation, compacted on the account it leaves and restarted under another account's credential store with a first prompt that asks Claude to continue. Works across many concurrent sessions, which spread over the pool instead of draining one account together. When the whole pool is at its limit, a session queues first come first served for a reset (at most eight sessions wait on one account; overflow waits for the next reset with room) and pauses with a countdown until its assigned reset, when that reset falls within twice `policy.maxWaitMs` (default 1h - a longer wait stays put rather than parking your terminal for hours).
 
-> **Scope:** Claude Code on macOS and Linux, plus OpenAI's Codex CLI and Muse Code as further switching pools; grok as a status-only pool. It pools **subscription** accounts (Pro/Max), not API keys.
+> **Scope:** Claude Code on macOS and Linux, plus OpenAI's Codex CLI and Muse Code as further switching pools; grok and Cursor as status-only pools. It pools **subscription** accounts (Pro/Max), not API keys.
 
 ```
 $ claude
@@ -40,15 +40,16 @@ claude                  # use claude as always; each session gets its own accoun
 | `tokenmaxxing init --codex` | same for codex: log in the first account (isolated), install codex supervisor + Stop hook |
 | `tokenmaxxing init --pi` | verify and pin the real `pi` and install the `pi` supervisor, which runs pi sessions on pooled Claude and ChatGPT accounts that have a pi login |
 | `tokenmaxxing init --grok` | pool the first grok login, status-only: no supervisor, no switching |
+| `tokenmaxxing init --cursor` | pool the Cursor CLI login, status-only: no supervisor, no switching |
 | `tokenmaxxing init --muse` | same for Muse Code: log in the first account (isolated), install the `muse` supervisor, which starts each session on the freshest account and resumes it on another near quota |
-| `tokenmaxxing add [--codex \| --grok \| --muse]` | register an additional account in that pool (isolated login, harvested once into its own store) |
-| `tokenmaxxing auth [--codex \| --grok \| --muse] [sel \| --all]` | reauthenticate a pooled account in place: bare lists the pool (emails shown) and asks which; a selector targets one account and tells you the email to sign in with; `--all` walks every account that is flagged or has no usable credential in its store, one by one |
+| `tokenmaxxing add [--codex \| --grok \| --muse \| --cursor]` | register an additional account in that pool (isolated login, harvested once into its own store) |
+| `tokenmaxxing auth [--codex \| --grok \| --muse \| --cursor] [sel \| --all]` | reauthenticate a pooled account in place: bare lists the pool (emails shown) and asks which; a selector targets one account and tells you the email to sign in with; `--all` walks every account that is flagged or has no usable credential in its store, one by one |
 | `tokenmaxxing auth --pi [--codex] [sel \| --all]` | log a pooled Claude account (or a codex account with `--codex`) into pi, isolated, and keep that login as the account's pi credential after an identity check; `--all` walks every account without a pi login |
 | `tokenmaxxing status [--cached]` | every pool: accounts with 5h / weekly / per-model usage bars, live session counts, exhausted-until-reset; `--cached` renders the stored figures without sampling |
 | `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 check` | fold fresh tees, sample up to three stale accounts, and self-update a Bun global install once a day; the periodic timer runs this every tick |
 | `tokenmaxxing doctor` | verify the install: PATH order, `claudeBin`, the five settings entries, the timer, the hub service, the credential identity of every Codex store and of every Claude store whose access token is still fresh (an expiring Claude token is reported as unverifiable, not as a failure), codex hook trust, and shell aliases that shadow `claude` |
-| `tokenmaxxing rename [--codex \| --grok \| --muse] <sel> <label>` / `rm [...] <sel>` | manage a pool (one email can hold both a claude and a codex account); `rm` is refused for an account with a running supervised session |
+| `tokenmaxxing rename [--codex \| --grok \| --muse \| --cursor] <sel> <label>` / `rm [...] <sel>` | manage a pool (one email can hold both a claude and a codex account); `rm` is refused for an account with a running supervised session |
 | `tokenmaxxing serve` | serve the CLIProxyAPI-compatible usage API on `http://localhost:8317` (`hub.port`) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows the quota of every pooled Claude and Codex account; the management key is the contents of `hub-key` in the state directory, minted on the first run, and `init` runs it as a background service beside the check timer. Details in [Usage hub](docs/content/docs/hub.mdx) |
 | `tokenmaxxing uninstall [--yes]` | print the targets, then remove the shims, settings entries, codex Stop hook, check timer, hub service, and rc PATH line (accounts/stores kept); refused without `--yes` when `HOME` is the login home |
 | `--json` | machine-readable output: one JSON document on stdout for `status`, `config`, and `check` (`ok` mirrors the exit code, failures add `error`) |
@@ -126,6 +127,7 @@ pi keeps its own credential and refreshes it itself, so each pooled account gets
 - **Keychain (macOS).** The first keychain access for a new store happens inside the interactive `init`, `add`, or `auth` run, where a prompt can be answered, not inside a headless hook.
 - **Plaintext credentials (Linux).** Claude Code itself stores Linux credentials as a 0600 plaintext file; a store follows the same model.
 - **The status-only grok pool does not switch.** grok `status` shows the weekly subscription credit window, and no grok session moves.
+- **The status-only Cursor pool does not switch, and reads only a file login.** Cursor `status` shows the included usage of the monthly billing cycle. The Cursor CLI keeps its login in the keychain on macOS, which tokenmaxxing does not read, so the pool works where the login is `auth.json` (Linux).
 - **A Muse Code move stops the running turn.** `muse resume` takes no prompt, so a turn that was running when the move landed has to be sent again; `muse exec` and `muse serve` keep the account they started on.
 
 ## How it's built

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.174.0",
+  "version": "1.176.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/cli/auth.ts

@@ -13,7 +13,7 @@ import { c, count } from "./render.ts";
 import type { Account, AccountsIndex } from "../lib/types.ts";
 
 const AUTH_USAGE =
-  "usage: tokenmaxxing auth [--codex | --grok | --muse] [<email|label|id> | --all]\n       tokenmaxxing auth [--codex | --grok | --muse] --emails <email>...\n       tokenmaxxing auth --pi [--codex] [<email|label|id> | --all]";
+  "usage: tokenmaxxing auth [--codex | --grok | --muse | --cursor] [<email|label|id> | --all]\n       tokenmaxxing auth [--codex | --grok | --muse | --cursor] --emails <email>...\n       tokenmaxxing auth --pi [--codex] [<email|label|id> | --all]";
 const EMAILS_FLAG = "--emails";
 
 export type AuthPlan = { kind: "usage" } | { kind: "error"; message: string } | { kind: "pick" } | { kind: "targets"; ids: string[] };

package/src/cli/rename.ts

@@ -16,7 +16,7 @@ export function findAccount(accounts: Account[], selector: string): Account | un
 export async function cmdRename(p: Provider, argv: string[]): Promise<number> {
   const [selector, newLabel] = argv;
   if (!selector || !newLabel) {
-    emitError({ message: "usage: tokenmaxxing rename [--codex | --grok | --muse] <email|label|id> <new-label>", paint: plain });
+    emitError({ message: "usage: tokenmaxxing rename [--codex | --grok | --muse | --cursor] <email|label|id> <new-label>", paint: plain });
     return 2;
   }
   return withLock(p.pool.lockFile, async () => {

package/src/cli/status.ts

@@ -3,16 +3,19 @@ import { creditLeft, keySessions, loadApiKeys } from "../lib/apikeys.ts";
 import { claude } from "../lib/claude.ts";
 import { codex } from "../lib/codex.ts";
 import { grok } from "../lib/grok.ts";
+import { cursor } from "../lib/cursor.ts";
 import { muse } from "../lib/muse.ts";
 import { loadAccounts, loadConfig, saveAccounts } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
-import { codexPool, grokPool, musePool } from "../lib/paths.ts";
+import { codexPool, cursorPool, grokPool, musePool } from "../lib/paths.ts";
 import { barFor, bufferedUsed, earliestReset, gatedWindows, landGrant, landWindows, isExhausted, isSessionWindow, limitWindows, liveUsed, nextWeeklyReset, sessionWindow, thresholdBars, weeklyWindow } from "../lib/picker.ts";
 import type { Provider, SampleReport } from "../lib/provider.ts";
 import { usd } from "./key.ts";
 import { bar, c, count, emitJson, fmtAgo } from "./render.ts";
 import type { Account, AccountThresholds, Bars, Config, Thresholds, Window } from "../lib/types.ts";
 
+const WEEK_S = 7 * 86400;
+
 export type WindowReport = { usedPercentage: number; bufferedPercentage: number; resetsAt: number | null; windowSeconds: number | null };
 
 export type UsageReport = { fiveHour: WindowReport | null; week: WindowReport | null; limits: (WindowReport & { name: string })[] };
@@ -53,7 +56,7 @@ type StatusApiKey = {
   sessions: number;
 };
 
-export type StatusReport = { now: number; claude: PoolReport; codex: PoolReport; grok: PoolReport; muse: PoolReport; apiKeys?: StatusApiKey[] };
+export type StatusReport = { now: number; claude: PoolReport; codex: PoolReport; grok: PoolReport; muse: PoolReport; cursor: PoolReport; apiKeys?: StatusApiKey[] };
 
 function apiKeyReport(): StatusApiKey[] {
   const sessions = keySessions();
@@ -89,7 +92,7 @@ function currentWindow(a: Account, w: Window, bars: Bars | null, now: number): W
   return {
     usedPercentage: liveUsed(w, now),
     bufferedPercentage: bars == null ? liveUsed(w, now) : bufferedUsed(a, w, bars, now),
-    resetsAt: isSessionWindow(w) ? (passed ? null : w.resetsAt) : nextWeeklyReset(w.resetsAt, now),
+    resetsAt: isSessionWindow(w) || (w.windowSeconds ?? 0) > WEEK_S ? (passed ? null : w.resetsAt) : nextWeeklyReset(w.resetsAt, now),
     windowSeconds: w.windowSeconds,
   };
 }
@@ -161,6 +164,7 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
           if (a.lastUsageAt != null && (stored.lastUsageAt == null || a.lastUsageAt > stored.lastUsageAt)) {
             landWindows(stored, p.mergeWindows(a.windows, stored.windows), a.lastUsageAt, bars);
             stored.hasCredits = a.hasCredits;
+            if (a.email != null && stored.email == null && stored.label === stored.id.slice(0, 8)) stored.label = a.email;
             if (a.email != null) stored.email = a.email;
             if (a.tier != null) stored.tier = a.tier;
             dirty = true;
@@ -267,7 +271,7 @@ function card(p: Provider, a: StatusAccount, now: number, staleAfterMs: number):
   const lines = [headerLine({ ...a, name: a.label })];
   if (a.usage) {
     if (a.usage.fiveHour) lines.push(usageRow(`${Math.round((a.usage.fiveHour.windowSeconds ?? 0) / 3600)}h`, a.usage.fiveHour));
-    if (a.usage.week) lines.push(usageRow("week", a.usage.week));
+    if (a.usage.week) lines.push(usageRow((a.usage.week.windowSeconds ?? 0) > WEEK_S ? "month" : "week", a.usage.week));
     for (const w of a.usage.limits) lines.push(usageRow(p.windowLabel(w.name), w));
   }
   const notes: Note[] = [];
@@ -308,9 +312,10 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
     const codexPooled = loadAccounts(codexPool).accounts.length > 0;
     const grokPooled = loadAccounts(grokPool).accounts.length > 0;
     const musePooled = loadAccounts(musePool).accounts.length > 0;
+    const cursorPooled = loadAccounts(cursorPool).accounts.length > 0;
     if (claudeReport.accounts.length === 0) {
-      if (!codexPooled && !grokPooled && !musePooled && apiKeys.length === 0) {
-        console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`, `--grok`, `--muse`)"));
+      if (!codexPooled && !grokPooled && !musePooled && !cursorPooled && apiKeys.length === 0) {
+        console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`, `--grok`, `--muse`, `--cursor`)"));
         return 0;
       }
       console.log(c.dim("no claude accounts (run `tokenmaxxing init` to pool claude too)"));
@@ -324,8 +329,9 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
   const codexReport = await collect(codex, cfg, now, cached);
   const grokReport = await collect(grok, cfg, now, cached);
   const museReport = await collect(muse, cfg, now, cached);
+  const cursorReport = await collect(cursor, cfg, now, cached);
   if (json) {
-    const report: StatusReport = { now, claude: claudeReport, codex: codexReport, grok: grokReport, muse: museReport, ...(apiKeys.length > 0 ? { apiKeys } : {}) };
+    const report: StatusReport = { now, claude: claudeReport, codex: codexReport, grok: grokReport, muse: museReport, cursor: cursorReport, ...(apiKeys.length > 0 ? { apiKeys } : {}) };
     emitJson({ ok: true, ...report });
     return 0;
   }
@@ -338,5 +344,8 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
   if (museReport.accounts.length > 0) {
     renderPool(muse, museReport, `muse  (${count({ n: museReport.accounts.length, noun: "account" })})`, Date.now(), cfg.policy.usagePollTtlMs);
   }
+  if (cursorReport.accounts.length > 0) {
+    renderPool(cursor, cursorReport, `cursor  (${count({ n: cursorReport.accounts.length, noun: "account" })}, status-only)`, Date.now(), cfg.policy.usagePollTtlMs);
+  }
   return 0;
 }

package/src/entries/supervisor.ts

@@ -5,7 +5,7 @@ import { maxBy, omit } from "es-toolkit";
 import { z } from "zod";
 import { claudePool, paths, storeDirFor } from "../lib/paths.ts";
 import { CLAUDE_BIN, UNMANAGED_ENV, WRAP_DEPTH_ENV, resolveRealBin, wrapDepth } from "../lib/claudebin.ts";
-import { apiKeyEnv, clearSessionCost, foldCompactionCost, foldSessionCost, loadApiKeys, readApiKey, sendApiKey, usableApiKey, writeSessionCost } from "../lib/apikeys.ts";
+import { apiKeyEnv, clearSessionCost, foldCompactionCost, foldSessionCost, isOpenRouterKey, loadApiKeys, readApiKey, sendApiKey, usableApiKey, writeSessionCost } from "../lib/apikeys.ts";
 import { claude, pickLaunch, pickSeat, type LaunchTarget } from "../lib/claude.ts";
 import { compactClaudeSession } from "../lib/compact.ts";
 import { evaluateAndMaybeSwap, moveTarget } from "../lib/decide.ts";
@@ -366,11 +366,14 @@ function depletedLines(sid: string, until: number, text: string): string {
   );
 }
 
-function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; onKey: boolean }): string {
+function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; onKey: boolean; openRouter: boolean }): string {
   const where = input.onKey ? "on an API key, because every pooled account is at its limit or the previous key ran out" : "on an account with quota headroom";
-  const moved = input.compacted
+  const resumed = input.compacted
     ? `tokenmaxxing compacted this conversation and resumed the session ${where}.`
     : `tokenmaxxing resumed this session ${where}.`;
+  const moved = input.openRouter
+    ? `${resumed} The session now runs on a base URL that is not an Anthropic host, so Claude Code has turned tool search off: every tool schema is already loaded and the ToolSearch tool does not exist in this session. Call tools directly.`
+    : resumed;
   if (input.origin === "stop") {
     return `${moved} The previous turn finished before the move. If it waited on the user or completed the task, end this turn without restating it. If it waited on a background Bash task, Monitor, or Workflow run, relaunch that work, because the move ended it.`;
   }
@@ -715,7 +718,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     if (stream) process.stdout.write(systemLine(noticeSid, text));
     else process.stderr.write(terminal);
   };
-  let firstLine: string | null = null;
+  let pendingResume: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"] } | null = null;
   let respawns = 0;
   let wanted: { accountId: string | null; apiKeyId: string | null } | null = null;
   let refused: string[] = [];
@@ -741,13 +744,17 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       }
       const picked = target?.account ?? null;
       const key = target?.apiKey ?? null;
-      log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, key: key?.id, args: launchArgs.join(" "), injected: firstLine !== null });
+      const prompt = pendingResume === null ? null : resumePrompt({ ...pendingResume, onKey: key != null, openRouter: key != null && isOpenRouterKey(key) });
+      pendingResume = null;
+      const args = relay === null && prompt !== null ? [...launchArgs.slice(0, 2), prompt, ...launchArgs.slice(2)] : launchArgs;
+      const firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;
+      log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, key: key?.id, args: args.join(" "), injected: firstLine !== null });
       const open: OpenTasks = new Map();
       const tee = stream && (picked || existsSync(claudePool.apiKeysJson)) ? seatTee(picked?.id ?? null, model, open, sid) : null;
       const secret = key ? readApiKey(key) : null;
       const extra: "pipe"[] = secret == null ? [] : ["pipe"];
       const scrubbed = scrubCredEnv(childEnv);
-      const spawned = Bun.spawn([real, ...launchArgs], {
+      const spawned = Bun.spawn([real, ...args], {
         stdio: [relay === null ? "inherit" : "pipe", tee === null ? childStdout() : "pipe", "inherit", ...extra],
         env: {
           ...(picked ? { ...scrubbed, CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : key ? apiKeyEnv(scrubbed, key) : childEnv),
@@ -763,7 +770,6 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       if (secret != null) sendApiKey(spawned, secret);
       drainStdout = spawned.stdout instanceof ReadableStream ? relayStdout(spawned.stdout, tee ?? undefined) : null;
       if (relay !== null) relay.attach(spawned.stdin!, firstLine, pendingTranscript);
-      firstLine = null;
       if (picked || key) {
         await recordPresenceOrStop({
           child: spawned,
@@ -870,11 +876,10 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       wanted = depleted ? (key ? { accountId: null, apiKeyId: key.id } : null) : m.apiKeyId != null ? { accountId: null, apiKeyId: m.apiKeyId } : { accountId: m.accountId, apiKeyId: null };
       refused = m.refused ?? refused;
       saveSessionFlags(m.sessionId, persistable, process.cwd());
-      const prompt = resumable ? resumePrompt({ compacted, origin: m.origin, onKey: m.apiKeyId != null }) : null;
-      firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;
+      pendingResume = resumable ? { compacted, origin: m.origin } : null;
       pendingTranscript = resumable ? null : transcriptPath(m.sessionId);
       if (!restored.has(m.sessionId)) restored.set(m.sessionId, resumable ? restoredCost(m.sessionId) : 0);
-      launchArgs = [resumable ? "--resume" : "--session-id", m.sessionId, ...(relay === null && prompt !== null ? [prompt] : []), ...persistable];
+      launchArgs = [resumable ? "--resume" : "--session-id", m.sessionId, ...persistable];
       continue;
     }
     clearPresence({ dir: paths.presenceDir, id: sid });

package/src/lib/cursor.ts

@@ -0,0 +1,185 @@
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.ts";
+import { http, safeErrorDetail } from "./http.ts";
+import { errorMessage } from "./log.ts";
+import { cursorAuthJsonFor, cursorPaths, cursorPool, cursorStoreDirFor, env } from "./paths.ts";
+import type { SampleReport } from "./provider.ts";
+import { readJsonFile, type Harvest } from "./state.ts";
+import { statusOnlyProvider, type AuthEntry } from "./statusonly.ts";
+import { ErrnoSchema, JsonTextSchema, type Account, type Window } from "./types.ts";
+import { c } from "../cli/render.ts";
+
+const CursorAuthSchema = z.looseObject({ accessToken: z.string().optional() });
+type CursorAuth = z.infer<typeof CursorAuthSchema>;
+
+const CliConfigSchema = z.looseObject({
+  authInfo: z.looseObject({ authId: z.string().optional(), email: z.string().nullish() }).optional(),
+});
+
+const JwtPayloadSchema = z.looseObject({ sub: z.string().min(1) });
+
+function readOptional<T>(path: string, schema: z.ZodType<T>): T | null {
+  try {
+    return readJsonFile(path, schema);
+  } catch (e) {
+    if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+function tokenSubject(token: string): string | null {
+  const payload = token.split(".")[1] ?? "";
+  return JwtPayloadSchema.safeParse(JsonTextSchema.safeParse(Buffer.from(payload, "base64url").toString("utf8")).data).data?.sub ?? null;
+}
+
+// The CLI caches the signed-in user next to auth.json; it is the only local copy of the email, because the token carries none.
+function cachedEmail(authPath: string, subject: string): string | null {
+  let config: z.infer<typeof CliConfigSchema> | null;
+  try {
+    config = readOptional(join(dirname(authPath), "cli-config.json"), CliConfigSchema);
+  } catch {
+    return null;
+  }
+  const info = config?.authInfo;
+  if (info?.authId !== subject) return null;
+  const email = info.email?.trim().toLowerCase() ?? "";
+  return email === "" ? null : email;
+}
+
+const harvestTokens = new WeakMap<Harvest, string>();
+
+function readAuth(path: string): AuthEntry[] {
+  const file: CursorAuth | null = readOptional(path, CursorAuthSchema);
+  const token = file?.accessToken ?? "";
+  if (file == null || token === "") return [];
+  const subject = tokenSubject(token);
+  if (subject == null) return [{ id: "", usable: false, harvest: null }];
+  const id = new Bun.CryptoHasher("sha256").update(subject).digest("hex");
+  const harvest: Harvest = {
+    id,
+    email: cachedEmail(path, subject),
+    tier: null,
+    sample: null,
+    park: async () => {
+      writeFileAtomic(cursorAuthJsonFor(id), JSON.stringify(file, null, 2), 0o600);
+    },
+  };
+  harvestTokens.set(harvest, token);
+  return [{ id, usable: true, harvest }];
+}
+
+const EpochMsSchema = z.coerce.number();
+
+const PeriodUsageSchema = z.looseObject({
+  billingCycleStart: EpochMsSchema,
+  billingCycleEnd: EpochMsSchema,
+  planUsage: z
+    .looseObject({
+      includedSpend: z.number().default(0),
+      limit: z.number().default(0),
+      totalPercentUsed: z.number().optional(),
+      apiPercentUsed: z.number().optional(),
+    })
+    .optional(),
+});
+
+const PlanInfoSchema = z.looseObject({ planInfo: z.looseObject({ planName: z.string().optional() }).optional() });
+
+const MeSchema = z.looseObject({ email: z.string().optional() });
+
+function dashboardUrl(method: string): string {
+  return `${env("TOKENMAXXING_CURSOR_API_URL", "https://api2.cursor.sh")}/aiserver.v1.DashboardService/${method}`;
+}
+
+async function dashboard(token: string, method: string): Promise<Response> {
+  return http.post(dashboardUrl(method), { headers: { Authorization: `Bearer ${token}`, "Connect-Protocol-Version": "1" }, json: {} });
+}
+
+async function dashboardField<T>(token: string, method: string, schema: z.ZodType<T>): Promise<T | null> {
+  try {
+    const res = await dashboard(token, method);
+    return res.ok ? (schema.safeParse(JsonTextSchema.safeParse(await res.text()).data).data ?? null) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readCursorUsage(account: Account, now: number): Promise<SampleReport> {
+  let token: string;
+  try {
+    token = readOptional(cursorAuthJsonFor(account.id), CursorAuthSchema)?.accessToken ?? "";
+  } catch (e) {
+    return { ok: false, reason: `this account's store is unreadable (${errorMessage(e)}) - run \`tokenmaxxing auth --cursor\`` };
+  }
+  if (token === "") return { ok: false, reason: "no accessToken in this account's store - run `tokenmaxxing auth --cursor`" };
+  let res: Response;
+  let text: string;
+  const plan = dashboardField(token, "GetPlanInfo", PlanInfoSchema);
+  const me = account.email == null ? dashboardField(token, "GetMe", MeSchema) : null;
+  try {
+    res = await dashboard(token, "GetCurrentPeriodUsage");
+    text = await res.text();
+  } catch (e) {
+    return { ok: false, reason: `Cursor usage read failed: endpoint unreachable: ${errorMessage(e)}` };
+  }
+  if (res.status === 401 || res.status === 403) {
+    account.needsReauth = true;
+    return { ok: false, reason: `Cursor rejected the stored login (HTTP ${res.status}) - run \`tokenmaxxing auth --cursor\`` };
+  }
+  if (!res.ok) return { ok: false, reason: `Cursor usage read failed: HTTP ${res.status}: ${safeErrorDetail({ text })}` };
+  const parsed = PeriodUsageSchema.safeParse(JsonTextSchema.safeParse(text).data);
+  if (!parsed.success) return { ok: false, reason: "Cursor usage read failed: endpoint returned an unexpected body shape (withheld)" };
+  const { billingCycleStart, billingCycleEnd, planUsage } = parsed.data;
+  const total = planUsage?.totalPercentUsed ?? (planUsage != null && planUsage.limit > 0 ? Math.min(100, (planUsage.includedSpend / planUsage.limit) * 100) : null);
+  if (total == null) return { ok: false, reason: "Cursor reports no included-usage limit for this account" };
+  const cycle = { resetsAt: billingCycleEnd, windowSeconds: billingCycleEnd > billingCycleStart ? Math.round((billingCycleEnd - billingCycleStart) / 1000) : null, sampledAt: now };
+  const windows: Window[] = [{ name: null, usedPercentage: total, ...cycle }];
+  if (planUsage?.apiPercentUsed != null) windows.push({ name: "API", usedPercentage: planUsage.apiPercentUsed, ...cycle });
+  account.windows = windows;
+  account.lastUsageAt = now;
+  const planName = (await plan)?.planInfo?.planName?.trim().toLowerCase();
+  if (planName) account.tier = planName;
+  const email = (await me)?.email?.trim().toLowerCase();
+  if (email) account.email = email;
+  return { ok: true, source: "probe" };
+}
+
+async function identify(harvest: Harvest): Promise<void> {
+  const token = harvestTokens.get(harvest);
+  if (harvest.email != null || token == null) return;
+  const email = (await dashboardField(token, "GetMe", MeSchema))?.email?.trim().toLowerCase();
+  if (email) harvest.email = email;
+}
+
+async function samplePool(accounts: Account[], now: number): Promise<Map<string, SampleReport>> {
+  const reports = new Map<string, SampleReport>();
+  await Promise.all(accounts.map(async (account) => reports.set(account.id, await readCursorUsage(account, now))));
+  return reports;
+}
+
+export const cursor = statusOnlyProvider({
+  name: "cursor",
+  flag: " --cursor",
+  pool: cursorPool,
+  binName: "cursor-agent",
+  binKey: "cursorBin",
+  storeDirFor: cursorStoreDirFor,
+  authJsonFor: cursorAuthJsonFor,
+  homeEnv: "XDG_CONFIG_HOME",
+  loginArgs: ["login"],
+  onboardAuthRel: "cursor/auth.json",
+  liveAuthPath: () => cursorPaths.authJson,
+  readAuth,
+  liveId: () => null,
+  presence: () => new Map(),
+  versionOk: (out) => /^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/.test(out.trim()),
+  importIntro: "Opening an isolated Cursor login for your first pooled account - the login you already have stays as it is.",
+  foundLive: () => `found the Cursor login in ${cursorPaths.authJson} - pooling it; use \`tokenmaxxing add --cursor\` for more.`,
+  install: () => {
+    console.log(c.dim("cursor pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled Cursor accounts."));
+  },
+  loginStep: () => `Approve the login in the browser that ${c.bold("cursor-agent login")} opens.`,
+  samplePool,
+  identify,
+});

package/src/lib/onboard.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { paths } from "./paths.ts";
 import { pidExists } from "./proc.ts";
 
-const POOLS = ["claude", "codex", "pi", "grok", "muse"] as const;
+const POOLS = ["claude", "codex", "pi", "grok", "muse", "cursor"] as const;
 
 export type OnboardPool = (typeof POOLS)[number];
 

package/src/lib/paths.ts

@@ -63,6 +63,11 @@ export const musePool = {
   lockFile: join(TM_HOME, "muse-lock"),
 } as const;
 
+export const cursorPool = {
+  accountsJson: join(TM_HOME, "cursor-accounts.json"),
+  lockFile: join(TM_HOME, "cursor-lock"),
+} as const;
+
 export type PoolPaths = { accountsJson: string; lockFile: string };
 
 const CODEX_HOME = env("TOKENMAXXING_CODEX_HOME", env("CODEX_HOME", join(HOME, ".codex")));
@@ -161,6 +166,19 @@ export function museSeatFromEnv(accountIds: string[], env: Record<string, string
   return accountIds.find((id) => museStoreDirFor(id) === home) ?? null;
 }
 
+export const cursorPaths = {
+  authJson: join(env("XDG_CONFIG_HOME", join(HOME, ".config")), "cursor", "auth.json"),
+  storesDir: join(TM_HOME, "cursor-stores"),
+} as const;
+
+export function cursorStoreDirFor(accountId: string): string {
+  return join(cursorPaths.storesDir, shortId(accountId));
+}
+
+export function cursorAuthJsonFor(accountId: string): string {
+  return join(cursorStoreDirFor(accountId), "auth.json");
+}
+
 export function grokSeatFromEnv(accountIds: string[], env: Record<string, string | undefined> = process.env): string | null {
   const home = env.GROK_HOME;
   if (home == null || home === "") return null;

package/src/lib/provider.ts

@@ -26,7 +26,7 @@ export class StoreUnusableError extends Error {
 }
 
 export type Provider = {
-  name: "claude" | "codex" | "grok" | "muse";
+  name: "claude" | "codex" | "grok" | "muse" | "cursor";
   flag: string;
   pool: PoolPaths;
   seats: "shared" | "live";

package/src/lib/sessions.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, realpathSync, rmSync, statSync, type Dirent }
 import { basename, join, sep } from "node:path";
 import { z } from "zod";
 import { errorMessage, log } from "./log.ts";
-import { codexPaths, grokPaths, musePaths, paths, piPaths } from "./paths.ts";
+import { codexPaths, cursorPaths, grokPaths, musePaths, paths, piPaths } from "./paths.ts";
 import { stagingTarget, writeFileAtomic } from "./atomic.ts";
 import { presencePid } from "./presence.ts";
 import { readJsonFile } from "./state.ts";
@@ -44,7 +44,7 @@ function recordLiveSession(sid: string, current: string): void {
 
 const TMP_GRACE_MS = 3600 * 1000;
 
-const SWEEP_PARENTS = [paths.storesDir, codexPaths.storesDir, grokPaths.storesDir, musePaths.storesDir, join(piPaths.storesDir, "claude"), join(piPaths.storesDir, "codex"), paths.costDir];
+const SWEEP_PARENTS = [paths.storesDir, codexPaths.storesDir, grokPaths.storesDir, musePaths.storesDir, cursorPaths.storesDir, join(piPaths.storesDir, "claude"), join(piPaths.storesDir, "codex"), paths.costDir];
 
 function listDir(dir: string, root: string): Dirent[] {
   if (!existsSync(dir)) return [];

package/src/lib/state.ts

@@ -35,11 +35,12 @@ export function loadConfig(): Config {
   cfg.codexBin = optionalEnv("TOKENMAXXING_CODEX_BIN") ?? cfg.codexBin;
   cfg.grokBin = optionalEnv("TOKENMAXXING_GROK_BIN") ?? cfg.grokBin;
   cfg.museBin = optionalEnv("TOKENMAXXING_MUSE_BIN") ?? cfg.museBin;
+  cfg.cursorBin = optionalEnv("TOKENMAXXING_CURSOR_BIN") ?? cfg.cursorBin;
   cfg.piBin = optionalEnv("TOKENMAXXING_PI_BIN") ?? cfg.piBin;
   return cfg;
 }
 
-export type BinKey = "claudeBin" | "codexBin" | "grokBin" | "museBin" | "piBin";
+export type BinKey = "claudeBin" | "codexBin" | "grokBin" | "museBin" | "cursorBin" | "piBin";
 
 export function pinBinOverride(input: { key: BinKey; bin: string }): void {
   const raw: Record<string, unknown> = existsSync(paths.configJson) ? readJsonFile(paths.configJson, z.record(z.string(), z.unknown())) : {};

package/src/lib/statusonly.ts

@@ -15,7 +15,7 @@ export type StatusOnlySpec = {
   flag: string;
   pool: PoolPaths;
   binName: string;
-  binKey: "grokBin" | "museBin";
+  binKey: "grokBin" | "museBin" | "cursorBin";
   storeDirFor: (accountId: string) => string;
   authJsonFor: (accountId: string) => string;
   homeEnv: string;
@@ -31,6 +31,7 @@ export type StatusOnlySpec = {
   install: () => void;
   loginStep: () => string;
   samplePool: Provider["samplePool"];
+  identify?: (harvest: Harvest) => Promise<void>;
 };
 
 // An entry with no identity (a Muse Code provider without an email) has no harvest; the first one that has one is pooled.
@@ -62,6 +63,7 @@ export function statusOnlyProvider(spec: StatusOnlySpec): Provider {
     try {
       const harvest = p.exitCode === 0 ? firstHarvest(spec.readAuth(join(onboardDir, spec.onboardAuthRel))) : null;
       if (!harvest) console.error(c.red(`no ${spec.name} login landed in the isolated home - nothing added.`));
+      else await spec.identify?.(harvest);
       return harvest;
     } finally {
       rmSync(onboardDir, { recursive: true, force: true });
@@ -75,6 +77,7 @@ export function statusOnlyProvider(spec: StatusOnlySpec): Provider {
     const harvest = live[0]?.harvest;
     if (!harvest) return login();
     console.log(c.dim(spec.foundLive(live.length)));
+    await spec.identify?.(harvest);
     return harvest;
   }
 

package/src/lib/types.ts

@@ -117,6 +117,7 @@ export const ConfigSchema = z
     codexBin: z.string().default(""),
     grokBin: z.string().default(""),
     museBin: z.string().default(""),
+    cursorBin: z.string().default(""),
     piBin: z.string().default(""),
     policy: z
       .object({

package/src/main.ts

@@ -14,6 +14,7 @@ import { runMuseSupervisor } from "./entries/musesupervisor.ts";
 import { claude } from "./lib/claude.ts";
 import { codex } from "./lib/codex.ts";
 import { grok } from "./lib/grok.ts";
+import { cursor } from "./lib/cursor.ts";
 import { muse } from "./lib/muse.ts";
 import { cmdInit, cmdInitPi } from "./cli/init.ts";
 import { cmdAdd } from "./cli/add.ts";
@@ -39,6 +40,7 @@ const YES_FLAG = "--yes";
 const CODEX_FLAG = "--codex";
 const GROK_FLAG = "--grok";
 const MUSE_FLAG = "--muse";
+const CURSOR_FLAG = "--cursor";
 const PI_FLAG = "--pi";
 const JSON_COMMANDS = new Set(["status", "config", "check"]);
 const CODEX_COMMANDS = new Set(["init", "add", "auth", "emails", "rm", "rename", "seat"]);
@@ -55,17 +57,18 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing init --pi")}     install the pi supervisor: pi sessions run on pooled Claude or ChatGPT accounts that are logged into pi
   ${c.cyan("tokenmaxxing init --grok")}   pool grok Build logins (status-only: no supervisor yet)
   ${c.cyan("tokenmaxxing init --muse")}   same for Muse Code: log in the first account, isolated, install the muse supervisor
+  ${c.cyan("tokenmaxxing init --cursor")} pool Cursor CLI logins (status-only: no supervisor yet)
   ${c.cyan("tokenmaxxing add")}        register an additional account (isolated login)
-  ${c.cyan("tokenmaxxing add")} --codex | --grok | --muse   same for the codex, grok, or muse pool
-  ${c.cyan("tokenmaxxing auth")} [--codex | --grok | --muse] [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every account that is flagged or has no usable credential in its store, one by one)
-  ${c.cyan("tokenmaxxing auth")} [--codex | --grok | --muse] --emails <email>...  log in and pool each listed email, skipping the ones already pooled (for moving to a new host: paste the output of ${c.cyan("emails")} from the old one)
-  ${c.cyan("tokenmaxxing emails")} [--codex | --grok | --muse]  print every pooled account's email, one per line, to copy into ${c.cyan("auth --emails")} on another host
+  ${c.cyan("tokenmaxxing add")} --codex | --grok | --muse | --cursor   same for the codex, grok, muse, or cursor pool
+  ${c.cyan("tokenmaxxing auth")} [--codex | --grok | --muse | --cursor] [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every account that is flagged or has no usable credential in its store, one by one)
+  ${c.cyan("tokenmaxxing auth")} [--codex | --grok | --muse | --cursor] --emails <email>...  log in and pool each listed email, skipping the ones already pooled (for moving to a new host: paste the output of ${c.cyan("emails")} from the old one)
+  ${c.cyan("tokenmaxxing emails")} [--codex | --grok | --muse | --cursor]  print every pooled account's email, one per line, to copy into ${c.cyan("auth --emails")} on another host
   ${c.cyan("tokenmaxxing auth --pi")} [--codex] [sel | --all]  log a pooled Claude account (or a codex account with --codex) into pi, isolated (bare = pick from a list; --all = every account without a pi login)
   ${c.cyan("tokenmaxxing status")} [--cached]  accounts with 5h / weekly / per-model usage bars (--cached: the stored figures, no sampling)
   ${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 | --grok | --muse] <sel> <label>
-  ${c.cyan("tokenmaxxing rm")} [--codex | --grok | --muse] <sel>
+  ${c.cyan("tokenmaxxing rename")} [--codex | --grok | --muse | --cursor] <sel> <label>
+  ${c.cyan("tokenmaxxing rm")} [--codex | --grok | --muse | --cursor] <sel>
   ${c.cyan("tokenmaxxing key add")} <label> [credit-usd] [workspace-id]  store an Anthropic or OpenRouter (sk-or-...) API key read from stdin or the prompt; Claude sessions run on it only while every pooled Claude account is at its limit (workspace-id: for a key that spans several workspaces; an OpenRouter key takes neither argument and reads its credit from OpenRouter)
   ${c.cyan("tokenmaxxing key credit")} <label> <usd>  set the key's balance as the Console shows it and restart its spend count (an OpenRouter key takes no amount: key credit <label> clears its refusal)
   ${c.cyan("tokenmaxxing key rm")} <label>  delete the key and its stored secret (refused while a session runs on it)
@@ -108,14 +111,14 @@ async function main(): Promise<number> {
   const json = jsonMode;
   const cached = argv.includes(CACHED_FLAG);
   const yes = argv.includes(YES_FLAG);
-  const providerFlags = [CODEX_FLAG, GROK_FLAG, MUSE_FLAG].filter((f) => argv.includes(f));
+  const providerFlags = [CODEX_FLAG, GROK_FLAG, MUSE_FLAG, CURSOR_FLAG].filter((f) => argv.includes(f));
   if (providerFlags.length > 1) {
     emitError({ json, message: `${providerFlags.join(" and ")} are mutually exclusive - pick one pool` });
     return 2;
   }
-  const provider = argv.includes(CODEX_FLAG) ? codex : argv.includes(GROK_FLAG) ? grok : argv.includes(MUSE_FLAG) ? muse : claude;
+  const provider = argv.includes(CODEX_FLAG) ? codex : argv.includes(GROK_FLAG) ? grok : argv.includes(MUSE_FLAG) ? muse : argv.includes(CURSOR_FLAG) ? cursor : claude;
   const pi = argv.includes(PI_FLAG);
-  const args = argv.filter((a) => a !== JSON_FLAG && a !== CACHED_FLAG && a !== YES_FLAG && a !== CODEX_FLAG && a !== GROK_FLAG && a !== MUSE_FLAG && a !== PI_FLAG);
+  const args = argv.filter((a) => a !== JSON_FLAG && a !== CACHED_FLAG && a !== YES_FLAG && a !== CODEX_FLAG && a !== GROK_FLAG && a !== MUSE_FLAG && a !== CURSOR_FLAG && a !== PI_FLAG);
   const sub = args[0];
 
   if (pi && sub !== "init" && sub !== "auth") {
@@ -143,7 +146,7 @@ async function main(): Promise<number> {
     return 2;
   }
 
-  if ((provider === grok || provider === muse) && (sub == null || !POOL_COMMANDS.has(sub))) {
+  if ((provider === grok || provider === muse || provider === cursor) && (sub == null || !POOL_COMMANDS.has(sub))) {
     emitError({ json, message: `${provider.flag.trim()} applies to ${[...POOL_COMMANDS].join(", ")}, not ${sub ?? "status"}` });
     return 2;
   }
@@ -215,7 +218,7 @@ async function main(): Promise<number> {
       if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${deactivationHint(CHECK_JOB)}`));
       if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${deactivationHint(HUB_JOB)}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
-      console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; pi: pi-stores/; grok: grok-stores/; muse: muse-stores/), plus api-keys.json and the API keys in api-keys/ - remove accounts with \`xx rm\` and keys with \`xx key rm\` to delete their credentials`);
+      console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; pi: pi-stores/; grok: grok-stores/; muse: muse-stores/; cursor: cursor-stores/), plus api-keys.json and the API keys in api-keys/ - remove accounts with \`xx rm\` and keys with \`xx key rm\` to delete their credentials`);
       return 0;
     }
     case "help":