tokenmaxxing-cli 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# tokenmaxxing-cli
+
+Paste this into your coding agent:
+
+```
+Set up tokenmaxxing for me: run `npx tokenmaxxing-cli@latest init`, show me the report it prints,
+and if I like it run `npx tokenmaxxing-cli link` and open the URL it prints.
+Don't edit any of my tool config files unless I say so.
+```
+
+`tokenmaxxing` reads the usage logs your AI coding tools already keep on disk (Claude Code, Codex,
+Gemini CLI), prices every token at API rates, and tells you what your subscription is worth:
+
+```
+tokenmaxxing · last 30 days · 2026-08-23 → 2026-09-22 · pricing snapshot 2026-09-22
+
+SOURCE   MODEL              INPUT   CACHE R   CACHE W   OUTPUT   API-EQUIV
+claude   claude-opus-5-5     2.9k    317.5M      8.9M   217.9k     $112.38
+codex    gpt-6-astra        24.4M      1.1B         0     2.5M   $1,500.63
+──────────────────────────────────────────────────────────────────────────
+TOTAL                       24.4M      1.4B      8.9M     2.7M   $1,613.01
+
+Plans:  claude  1× max-20x  = $200/mo  → API-equivalent $112.38  → ROI 0.6×
+Unpriced models (0 tokens counted toward $): none
+```
+
+The package name is `tokenmaxxing-cli`; the command it installs is `tokenmaxxing`. (The bare
+`tokenmaxxing` package on npm is an unrelated project.)
+
+## Privacy
+
+- **Local logs only.** It reads `~/.claude/projects/**/*.jsonl` (or `CLAUDE_CONFIG_DIR`),
+  `~/.codex/sessions` + `archived_sessions` (or `CODEX_HOME`) and `~/.gemini/tmp/*/chats/*.json`.
+  From those lines it keeps token counts, model names and timestamps; prompts, code, paths and
+  project names are never stored.
+- **Never touches sign-in data.** No keychain access, no auth or token files of any tool, no provider
+  API calls. A test fails the build if the source ever mentions them.
+- **No telemetry.** Nothing leaves your machine unless you run `tokenmaxxing push`, which prints exactly
+  what it will send (hourly bucket rows: timestamp, source, model, token counts) before sending it.
+- **Never edits other tools' configs** unless you run `tokenmaxxing hook install` and confirm the diff.
+- **Zero runtime dependencies.** Pricing is a bundled snapshot of LiteLLM + models.dev; unknown models
+  are listed as *unpriced*, never silently counted as $0.
+
+Everything it writes lives in `~/.tokenmaxxing/` (override with `TOKENMAXXING_HOME`):
+`config.json`, `buckets.jsonl` (one row per hour × source × model) and `cursors.json` (per-file read
+offsets so each `sync` only reads what's new).
+
+## Commands
+
+```
+tokenmaxxing init                          detect tools, write config, first sync, print report
+tokenmaxxing sync [--quiet]                incremental parse of all detected sources
+tokenmaxxing report [--since 7d|30d|YYYY-MM-DD] [--json] [--by model|source|day]
+tokenmaxxing plan set <provider> <plan> [xN]   replace a provider's plans (qty N, default 1)
+tokenmaxxing plan add <provider> <plan> [xN]   add a line; several plans per provider add up
+                                           claude: pro | max-5x | max-20x | team-standard | team-premium
+                                           openai: go | plus | pro-100 | pro | business   (ChatGPT; Codex is in Plus/Pro/Business)
+                                           cursor: pro | pro-plus | ultra | teams
+                                           google: ai-plus | ai-pro | ai-ultra-100 | ai-ultra
+                                           any:    custom <monthly> "<label>", e.g. plan add openai custom 100 "Codex $100 promo"
+tokenmaxxing plan remove <provider> [<plan>]   remove one line, or all of a provider's plans
+tokenmaxxing plan list                     your lines, monthly totals and every plan id with its price
+tokenmaxxing verify [--since 30d]          compare Claude totals with `ccusage` (if installed), 1% tolerance
+tokenmaxxing link [--site URL]             prints a sign-in URL, waits for the site, stores the token
+tokenmaxxing push [--site URL] [--dry-run] [--all] [--granularity hour|day|week]
+                                           upload bucket rows (opt-in); prints what is sent
+tokenmaxxing granularity [set hour|day|week]  hour (default) uploads hourly rows; day or week uploads
+                                           totals only, so the site never sees which hours you work
+tokenmaxxing hook install|uninstall|status [--yes]      Claude Code Stop hook + Codex notify hook running `sync`
+tokenmaxxing schedule install|uninstall|status [--yes]  launchd (macOS) / cron (Linux), every 30 min
+tokenmaxxing doctor                        paths found, files scanned, cursor state, pricing snapshot date
+tokenmaxxing --version
+```
+
+ROI = API-equivalent cost for the period ÷ (plan price × days ÷ 30.4375).
+
+Notes:
+
+- Cursor is detected but excluded from totals: its local database has no token counts.
+- `verify` groups by local calendar day because that is how `ccusage` groups. It checks input and cache tokens
+  at 1%; output is informational and expected higher, because ccusage counts only the first line of a message
+  that Claude Code writes as several lines, while tokenmaxxing counts its final usage. Costs differ from ccusage
+  by design: ccusage prices every cache write at the 5-minute rate; tokenmaxxing prices 1-hour cache
+  writes at the 1-hour rate.
+- `--site` (or `TOKENMAXXING_SITE`) points `link`/`push` at another server, e.g. `http://localhost:3000`.
+- Changing granularity (or `push --all`) tells the site to replace every row it holds for this device, so
+  switching between hourly and daily totals never double counts. The current day or week is resent on each
+  push until it is complete.
+- Custom prices: `src/pricing/overrides.json` in a checkout (`{ "<model>": { "input": 3, "output": 15,
+  "cache_read": 0.3, "cache_write_5m": 3.75, "cache_write_1h": 6 } }`, USD per million tokens) wins over
+  the snapshots; `{ "<model>": { "unpriced": "<note>" } }` keeps a model unpriced and shows the note (used for
+  Codex's bundled `codex-auto-review` and `gpt-reserve`, which have no list price).
+
+MIT licensed.

package/dist/bucket.js

@@ -0,0 +1,56 @@
+import { COUNT_FIELDS } from './types.js';
+export function emptyBucket(ts, source, model) {
+    return {
+        v: 1, ts, source, model,
+        input: 0, cache_read: 0, cache_write_5m: 0, cache_write_1h: 0, output: 0, reasoning: 0,
+        requests: 0, conversations: 0,
+    };
+}
+export function bucketKey(b) {
+    return `${b.ts}|${b.source}|${b.model}`;
+}
+/** Floor an ISO timestamp (or epoch ms) to the UTC hour: `2026-09-22T13:00:00Z`. Returns null if invalid. */
+export function hourOf(t) {
+    if (t === undefined || t === null || t === '')
+        return null;
+    const ms = typeof t === 'number' ? t : Date.parse(t);
+    if (!Number.isFinite(ms))
+        return null;
+    return new Date(ms).toISOString().slice(0, 13) + ':00:00Z';
+}
+/** Accumulates per-(hour, source, model) deltas produced by a parser run. */
+export class BucketAccumulator {
+    map = new Map();
+    get(ts, source, model) {
+        const key = `${ts}|${source}|${model}`;
+        let b = this.map.get(key);
+        if (!b) {
+            b = emptyBucket(ts, source, model);
+            this.map.set(key, b);
+        }
+        return b;
+    }
+    addUsage(ts, source, model, u, requests = 1) {
+        const b = this.get(ts, source, model);
+        b.input += u.input;
+        b.cache_read += u.cache_read;
+        b.cache_write_5m += u.cache_write_5m;
+        b.cache_write_1h += u.cache_write_1h;
+        b.output += u.output;
+        b.reasoning += u.reasoning;
+        b.requests += requests;
+    }
+    addConversation(ts, source, model, n = 1) {
+        this.get(ts, source, model).conversations += n;
+    }
+    rows() {
+        return [...this.map.values()];
+    }
+}
+export function addInto(target, delta) {
+    for (const f of COUNT_FIELDS)
+        target[f] += delta[f];
+}
+export function isZero(b) {
+    return COUNT_FIELDS.every((f) => b[f] === 0);
+}

package/dist/cli.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { configExists, loadConfig, saveConfig } from './config.js';
+import { isGranularity } from './config.js';
+import { detect, detectionToSources } from './detect.js';
+import { doctor } from './doctor.js';
+import { fmtInt, fmtPrice, table } from './format.js';
+import { hookCommand } from './hook.js';
+import { parsePeriod } from './period.js';
+import { addLine, CUSTOM, describeLines, isProvider, lineName, parsePlanSpec, planTable, plansMonthly, PROVIDERS, providerMonthly, unitPrice, } from './plans.js';
+import { buildReport, renderReport, reportJson } from './report.js';
+import { scheduleCommand } from './schedule.js';
+import { link, push, SiteError } from './site.js';
+import { loadBuckets } from './store.js';
+import { sync } from './sync.js';
+import { compare, ccusageTotals, ourTotals, runCcusage } from './verify.js';
+import { SOURCES } from './types.js';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const HELP = `tokenmaxxing ${VERSION} — API-equivalent value of your AI coding subscriptions, from local logs.
+
+Usage: tokenmaxxing <command> [options]
+
+  init                               detect tools, write config, first sync, print report
+  sync [--quiet]                     incremental parse of all detected sources
+  report [--since 7d|30d|YYYY-MM-DD] [--json] [--by model|source|day]
+  plan set <provider> <plan> [xN]    replace a provider's plans, e.g. plan set claude max-20x x5 · plan set openai pro
+  plan add <provider> <plan> [xN]    add a line, e.g. plan add claude pro · plan add openai custom 100 "Codex $100"
+  plan remove <provider> [<plan>]    remove one line, or all of a provider's plans (plan set <provider> none also clears)
+  plan list
+  verify [--since 30d]               compare Claude totals with ccusage (if installed)
+  link [--site URL]                  connect this machine to tokenmaxxing.fyi
+  push [--site URL] [--dry-run] [--all] [--granularity hour|day|week]
+                                     upload bucket rows (opt-in); prints what is sent; --all resends everything
+  granularity [set hour|day|week]    how coarse uploaded rows are (default hour; day/week hide your working hours)
+  hook install|uninstall|status [--yes]      opt-in Claude Code Stop / Codex notify hook
+  schedule install|uninstall|status [--yes]  run sync every 30 min (launchd / cron)
+  doctor                             paths, files scanned, cursor state, pricing snapshot
+  --version
+
+Data lives in ~/.tokenmaxxing (override with TOKENMAXXING_HOME). No telemetry.`;
+const VALUE_FLAGS = new Set(['since', 'by', 'site', 'qty']);
+export function parseArgs(argv) {
+    const out = { pos: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-h')
+            out.flags.help = true;
+        else if (a === '-v')
+            out.flags.version = true;
+        else if (a === '-y')
+            out.flags.yes = true;
+        else if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
+            if (eq !== -1)
+                out.flags[name] = a.slice(eq + 1);
+            else if (VALUE_FLAGS.has(name) && i + 1 < argv.length && !argv[i + 1].startsWith('--'))
+                out.flags[name] = argv[++i];
+            else
+                out.flags[name] = true;
+        }
+        else if (!out.cmd)
+            out.cmd = a;
+        else
+            out.pos.push(a);
+    }
+    return out;
+}
+const str = (v) => (typeof v === 'string' ? v : undefined);
+function syncSummary(r) {
+    const parts = Object.entries(r.perSource).map(([s, st]) => `${s} ${fmtInt(st.filesSeen)} files (${fmtInt(st.filesChanged)} changed, ${(st.bytesRead / 1e6).toFixed(0)} MB read)`);
+    return `Synced ${parts.join(' · ') || 'nothing (no sources enabled)'} → ${fmtInt(r.rowsWritten)} bucket rows in ${(r.ms / 1000).toFixed(1)}s`;
+}
+async function printReport(cfg, a) {
+    const period = parsePeriod(str(a.flags.since));
+    const byFlag = str(a.flags.by);
+    if (byFlag && !['model', 'source', 'day'].includes(byFlag))
+        throw new UsageError('--by expects model, source or day');
+    const by = (byFlag ?? 'source-model');
+    const { rows } = await loadBuckets();
+    const rep = buildReport(rows.values(), period, cfg, by);
+    console.log(a.flags.json ? reportJson(rep) : renderReport(rep));
+    return 0;
+}
+class UsageError extends Error {
+}
+async function main(argv) {
+    const a = parseArgs(argv);
+    if (a.flags.version || a.cmd === 'version') {
+        console.log(VERSION);
+        return 0;
+    }
+    if (a.flags.help || !a.cmd || a.cmd === 'help') {
+        console.log(HELP);
+        return a.cmd || a.flags.help ? 0 : 1;
+    }
+    const quiet = !!a.flags.quiet;
+    const yes = !!a.flags.yes;
+    switch (a.cmd) {
+        case 'init': {
+            const det = detect();
+            const cfg = loadConfig();
+            cfg.sources = detectionToSources(det);
+            saveConfig(cfg);
+            for (const s of SOURCES) {
+                const d = det[s];
+                if (s === 'cursor')
+                    console.log(`cursor  ${d.found ? `detected — ${d.note}` : 'not found'}`);
+                else
+                    console.log(`${s.padEnd(7)} ${d.found ? `found: ${d.paths.join(', ')}` : 'not found (disabled)'}`);
+            }
+            const r = await sync(cfg, (m) => process.stderr.write(`${m}\n`));
+            console.log(r.skippedLocked ? 'Another sync is running; showing current data.' : syncSummary(r));
+            console.log('');
+            await printReport(cfg, a);
+            console.log('');
+            console.log('Next: tokenmaxxing plan set <provider> <plan>  (for ROI)  ·  tokenmaxxing link  (to publish)');
+            return 0;
+        }
+        case 'sync': {
+            // Extra positional args are ignored (Codex `notify` appends a JSON payload).
+            const cfg = ensureConfig(quiet);
+            const r = await sync(cfg, quiet ? undefined : (m) => process.stderr.write(`${m}\n`));
+            if (!quiet)
+                console.log(r.skippedLocked ? 'Another sync is already running.' : syncSummary(r));
+            return 0;
+        }
+        case 'report': {
+            const cfg = ensureConfig(false);
+            return printReport(cfg, a);
+        }
+        case 'granularity': {
+            const cfg = loadConfig();
+            const [sub, val] = a.pos;
+            if (sub === 'set') {
+                if (!val || !isGranularity(val))
+                    throw new UsageError('granularity must be hour, day or week');
+                cfg.site.granularity = val;
+                saveConfig(cfg);
+                console.log(`Uploads will be ${val}ly totals${val === 'hour' ? '' : '; the site will not see which hours you work'}. The next push replaces this device's rows on the site.`);
+                return 0;
+            }
+            const cur = cfg.site.granularity ?? 'hour';
+            console.log(`${cur}  (hour = most detail on your profile · day/week = the site never sees your working hours)\nSet with: tokenmaxxing granularity set hour|day|week`);
+            return 0;
+        }
+        case 'plan':
+            return planCommand(a);
+        case 'verify': {
+            const cfg = ensureConfig(true);
+            const period = parsePeriod(str(a.flags.since) ?? '30d');
+            const since = period.sinceDate.replace(/-/g, '');
+            const cc = await runCcusage(since);
+            if (!cc.ok && cc.missing) {
+                console.log('ccusage is not installed, so there is nothing to compare against.');
+                console.log('Install it with `npm i -g ccusage` (or run `npx ccusage@latest daily`), then re-run `tokenmaxxing verify`.');
+                return 0;
+            }
+            if (!cc.ok) {
+                console.error(`ccusage failed: ${cc.error}`);
+                return 1;
+            }
+            // Sync after ccusage so our side has seen at least everything ccusage saw.
+            await sync(cfg);
+            const { rows } = await loadBuckets();
+            console.log(`verify · Claude · ${period.sinceDate} → ${period.untilDate} (local days, as ccusage groups them) · tolerance 1% on tokens\n`);
+            const res = compare(ourTotals(rows.values(), period), ccusageTotals(cc.json, period.sinceDate));
+            console.log(res.lines.join('\n'));
+            return res.pass ? 0 : 1;
+        }
+        case 'link': {
+            const cfg = ensureConfig(true);
+            await link(cfg, { site: str(a.flags.site) });
+            return 0;
+        }
+        case 'push': {
+            const cfg = ensureConfig(true);
+            const g = str(a.flags.granularity);
+            if (g !== undefined && !isGranularity(g))
+                throw new UsageError('--granularity must be hour, day or week');
+            await push(cfg, { site: str(a.flags.site), dryRun: !!a.flags['dry-run'], all: !!a.flags.all, granularity: g });
+            return 0;
+        }
+        case 'hook':
+            return hookCommand(a.pos[0], { yes });
+        case 'schedule':
+            return scheduleCommand(a.pos[0], { yes });
+        case 'doctor':
+            return doctor(VERSION);
+        default:
+            console.error(`Unknown command: ${a.cmd}\n`);
+            console.error(HELP);
+            return 1;
+    }
+}
+const PLAN_USAGE = 'usage: tokenmaxxing plan list | plan set <provider> <plan> [xN] | plan add <provider> <plan> [xN] | plan remove <provider> [<plan>]';
+function planSummary(provider, lines) {
+    return lines.length ? `${provider}: ${describeLines(lines)} = ${fmtPrice(providerMonthly(provider, lines))}/mo` : `${provider}: no plan`;
+}
+function planCommand(a) {
+    const cfg = loadConfig();
+    const [sub, provider, ...rest] = a.pos;
+    if (sub === 'list' || sub === undefined) {
+        const rows = [];
+        for (const p of PROVIDERS) {
+            const lines = cfg.plans[p] ?? [];
+            if (!lines.length)
+                rows.push([`  ${p}`, 'none', '', '']);
+            lines.forEach((l, i) => rows.push([i === 0 ? `* ${p}` : '', `${l.qty}× ${lineName(l)}`, `${fmtPrice(unitPrice(p, l))} each`, `${fmtPrice(unitPrice(p, l) * l.qty)}/mo`]));
+            if (lines.length > 1)
+                rows.push(['', `${p} total`, '', `${fmtPrice(providerMonthly(p, lines))}/mo`]);
+        }
+        console.log(table(['', '', '', ''], rows, ['l', 'l', 'r', 'r'], 3).slice(1).join('\n'));
+        if (Object.keys(cfg.plans).length)
+            console.log(`\nAll plans: ${fmtPrice(plansMonthly(cfg.plans))}/mo`);
+        const t = planTable();
+        console.log('\nAvailable (USD per month per seat):');
+        for (const p of PROVIDERS)
+            console.log(`  ${p.padEnd(7)} ${Object.entries(t[p]).map(([k, v]) => `${k} ${fmtPrice(v)}`).join(' · ')}`);
+        console.log(`  any     ${CUSTOM} <monthly> [label]   e.g. plan add openai custom 100 "Codex $100 promo"`);
+        console.log('\nChange with: tokenmaxxing plan add <provider> <plan> [xN] · plan set <provider> <plan> [xN] · plan remove <provider> [<plan>]   (* = has a plan)');
+        return 0;
+    }
+    if (sub !== 'set' && sub !== 'add' && sub !== 'remove')
+        throw new UsageError(PLAN_USAGE);
+    if (!provider || !isProvider(provider))
+        throw new UsageError(`provider must be one of: ${PROVIDERS.join(', ')}`);
+    const cur = cfg.plans[provider] ?? [];
+    let next;
+    if (sub === 'remove' || (sub === 'set' && (rest[0] === 'none' || rest[0] === 'off'))) {
+        const [plan, ...label] = rest;
+        if (sub === 'set' || plan === undefined)
+            next = [];
+        else {
+            const text = label.join(' ').trim();
+            const hits = cur.filter((l) => l.plan === plan && (plan !== CUSTOM || !text || l.label === text));
+            if (!hits.length)
+                throw new UsageError(`${provider} has no ${plan}${text ? ` "${text}"` : ''} line (${planSummary(provider, cur)})`);
+            if (hits.length > 1)
+                throw new UsageError(`${provider} has ${hits.length} custom lines; name one: ${hits.map((l) => `"${l.label}"`).join(', ')}`);
+            next = cur.filter((l) => l !== hits[0]);
+        }
+    }
+    else {
+        const line = parsePlanSpec(provider, rest, typeof a.flags.qty === 'string' ? a.flags.qty : a.flags.qty ? '' : undefined);
+        if (typeof line === 'string')
+            throw new UsageError(line);
+        if (sub === 'set')
+            next = [line];
+        else {
+            const merged = addLine(cur, line);
+            if (typeof merged === 'string')
+                throw new UsageError(merged);
+            next = merged;
+        }
+    }
+    if (next.length)
+        cfg.plans[provider] = next;
+    else
+        delete cfg.plans[provider];
+    saveConfig(cfg);
+    console.log(next.length ? planSummary(provider, next) : `Cleared ${provider} plan.`);
+    return 0;
+}
+/** Commands other than init work without a config by detecting sources on the fly (nothing is written). */
+function ensureConfig(quiet) {
+    const cfg = loadConfig();
+    if (!configExists()) {
+        cfg.sources = detectionToSources(detect());
+        if (!quiet)
+            process.stderr.write('No config yet (run `tokenmaxxing init`); using detected sources.\n');
+    }
+    return cfg;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (e) => {
+    if (e instanceof SiteError || e instanceof UsageError)
+        console.error(`tokenmaxxing: ${e.message}`);
+    else
+        console.error(e?.stack ?? String(e));
+    process.exitCode = 1;
+});

package/dist/config.js

@@ -0,0 +1,49 @@
+import { randomUUID } from 'node:crypto';
+import { files } from './paths.js';
+import { readJson, writeJsonAtomic, isFile } from './fsutil.js';
+import { normalizePlans } from './plans.js';
+export const DEFAULT_SITE = 'https://tokenmaxxing.fyi';
+export const GRANULARITIES = ['hour', 'day', 'week'];
+export function isGranularity(s) {
+    return GRANULARITIES.includes(s);
+}
+export function defaultConfig() {
+    return {
+        version: 1,
+        deviceId: randomUUID(),
+        sources: {
+            claude: { enabled: false, paths: [] },
+            codex: { enabled: false, paths: [] },
+            gemini: { enabled: false, paths: [] },
+            cursor: { enabled: false, paths: [] },
+        },
+        plans: {},
+        site: { url: DEFAULT_SITE },
+    };
+}
+export function configExists() {
+    return isFile(files.config());
+}
+export function loadConfig() {
+    const base = defaultConfig();
+    const raw = readJson(files.config(), null);
+    if (!raw)
+        return base;
+    return {
+        ...base,
+        ...raw,
+        version: 1,
+        deviceId: typeof raw.deviceId === 'string' && raw.deviceId ? raw.deviceId : base.deviceId,
+        sources: { ...base.sources, ...(raw.sources ?? {}) },
+        plans: normalizePlans(raw.plans),
+        site: { ...base.site, ...(raw.site ?? {}) },
+    };
+}
+export function saveConfig(cfg) {
+    writeJsonAtomic(files.config(), cfg);
+}
+/** Site URL precedence: --site flag > TOKENMAXXING_SITE env > config.site.url > default. */
+export function siteUrl(cfg, flag) {
+    const raw = flag || process.env.TOKENMAXXING_SITE || cfg.site.url || DEFAULT_SITE;
+    return raw.replace(/\/+$/, '');
+}

package/dist/cursors.js

@@ -0,0 +1,24 @@
+import { files } from './paths.js';
+import { readJson, writeJsonAtomic } from './fsutil.js';
+export function emptySourceCursor() {
+    return { files: {}, dedup: [], badLines: 0 };
+}
+export function loadCursors() {
+    const c = readJson(files.cursors(), null);
+    if (!c || c.v !== 1 || typeof c.sources !== 'object')
+        return { v: 1, sources: {} };
+    return c;
+}
+export function sourceCursor(c, name) {
+    if (!c.sources[name])
+        c.sources[name] = emptySourceCursor();
+    const s = c.sources[name];
+    s.files ??= {};
+    s.dedup ??= [];
+    s.badLines ??= 0;
+    return s;
+}
+export function saveCursors(c) {
+    // Compact JSON: dedup sets can hold hundreds of thousands of keys.
+    writeJsonAtomic(files.cursors(), c, false);
+}

package/dist/dedup.js

@@ -0,0 +1,46 @@
+/**
+ * Insertion-ordered Set with a size bound. `add` refreshes an existing key to most-recent,
+ * so eviction drops the least recently seen key. Serialises to a plain array (oldest first).
+ */
+export class BoundedSet {
+    limit;
+    set;
+    constructor(limit, init = []) {
+        this.limit = limit;
+        this.set = new Set(init);
+        this.trim();
+    }
+    has(k) {
+        return this.set.has(k);
+    }
+    /** Returns true if the key was new. */
+    add(k) {
+        if (this.set.has(k)) {
+            this.set.delete(k);
+            this.set.add(k);
+            return false;
+        }
+        this.set.add(k);
+        // Trim lazily in batches to keep add O(1) amortised.
+        if (this.set.size > this.limit * 1.25)
+            this.trim();
+        return true;
+    }
+    get size() {
+        return this.set.size;
+    }
+    trim() {
+        let excess = this.set.size - this.limit;
+        if (excess <= 0)
+            return;
+        for (const k of this.set) {
+            if (excess-- <= 0)
+                break;
+            this.set.delete(k);
+        }
+    }
+    toJSON() {
+        this.trim();
+        return [...this.set];
+    }
+}

package/dist/detect.js

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+import { isDir, isFile } from './fsutil.js';
+import { claudeCandidateRoots, codexHome, cursorTrackingDb, geminiHome } from './paths.js';
+/** Look for each tool's local log directory. Reads directory metadata only. */
+export function detect() {
+    const claudeRoots = claudeCandidateRoots().filter((r) => isDir(join(r, 'projects')));
+    const cx = codexHome();
+    const codexFound = isDir(join(cx, 'sessions')) || isDir(join(cx, 'archived_sessions'));
+    const gm = geminiHome();
+    const geminiFound = isDir(join(gm, 'tmp'));
+    const cursorDb = cursorTrackingDb();
+    const cursorFound = isFile(cursorDb);
+    return {
+        claude: { source: 'claude', found: claudeRoots.length > 0, paths: claudeRoots },
+        codex: { source: 'codex', found: codexFound, paths: codexFound ? [cx] : [] },
+        gemini: { source: 'gemini', found: geminiFound, paths: geminiFound ? [gm] : [] },
+        cursor: {
+            source: 'cursor',
+            found: cursorFound,
+            paths: cursorFound ? [cursorDb] : [],
+            note: 'token counts not available locally; Cursor is excluded from totals',
+        },
+    };
+}
+export function detectionToSources(d) {
+    const out = {};
+    for (const k of Object.keys(d))
+        out[k] = { enabled: d[k].found, paths: d[k].paths };
+    return out;
+}

package/dist/doctor.js

@@ -0,0 +1,48 @@
+import { configExists, loadConfig, siteUrl } from './config.js';
+import { loadCursors } from './cursors.js';
+import { detect } from './detect.js';
+import { fmtInt } from './format.js';
+import { isDir, isFile } from './fsutil.js';
+import { claudeSettingsPath, claudeHasHook, codexConfigPath, codexHasOurNotify } from './hook.js';
+import { files, tmxHome } from './paths.js';
+import { SNAPSHOT_DATE } from './pricing/index.js';
+import { loadBuckets } from './store.js';
+import { readFileSync } from 'node:fs';
+import { SOURCES } from './types.js';
+export async function doctor(version, log = console.log) {
+    const cfg = loadConfig();
+    const cursors = loadCursors();
+    log(`tokenmaxxing-cli ${version} · node ${process.version} · ${process.platform}`);
+    log(`home:     ${tmxHome()}${configExists() ? '' : '  (no config yet — run `tokenmaxxing init`)'}`);
+    log(`pricing:  bundled snapshot ${SNAPSHOT_DATE} (LiteLLM + models.dev, overrides.json)`);
+    log('');
+    const det = detect();
+    for (const s of SOURCES) {
+        const sc = cfg.sources[s];
+        const cur = cursors.sources[s];
+        log(`${s}: ${sc?.enabled ? 'enabled' : 'disabled'}${det[s].found ? '' : ' · not detected on this machine'}`);
+        for (const p of sc?.paths ?? [])
+            log(`  path  ${p}  ${isDir(p) || isFile(p) ? 'found' : 'MISSING'}`);
+        if (s === 'cursor' && det.cursor.found)
+            log(`  note  ${det.cursor.note}`);
+        if (cur) {
+            const tracked = Object.keys(cur.files ?? {}).length;
+            log(`  cursor  ${fmtInt(tracked)} files tracked · last sync ${cur.lastSync ?? 'never'} · last run scanned ${fmtInt(cur.lastFilesScanned ?? 0)}, changed ${fmtInt(cur.lastFilesChanged ?? 0)}`);
+            log(`          dedup keys ${fmtInt(cur.dedup?.length ?? 0)}${cur.convDedup ? ` · prompt keys ${fmtInt(cur.convDedup.length)}` : ''} · skipped garbled lines ${fmtInt(cur.badLines ?? 0)}`);
+        }
+    }
+    log('');
+    const b = await loadBuckets();
+    log(`buckets:  ${files.buckets()} · ${fmtInt(b.bytes)} bytes · ${fmtInt(b.lines)} lines · ${fmtInt(b.rows.size)} current rows${b.bad ? ` · ${b.bad} invalid lines` : ''}`);
+    let claudeHook = false;
+    try {
+        claudeHook = claudeHasHook(JSON.parse(isFile(claudeSettingsPath()) ? readFileSync(claudeSettingsPath(), 'utf8') : '{}'));
+    }
+    catch {
+        /* ignore */
+    }
+    const codexHook = isFile(codexConfigPath()) && codexHasOurNotify(readFileSync(codexConfigPath(), 'utf8'));
+    log(`hooks:    claude ${claudeHook ? 'installed' : 'not installed'} · codex ${codexHook ? 'installed' : 'not installed'}`);
+    log(`site:     ${siteUrl(cfg)} · ${cfg.site.token ? `linked${cfg.site.handle ? ` as @${cfg.site.handle}` : ''}` : 'not linked'}${cfg.site.lastPushedTs ? ` · last pushed ${cfg.site.lastPushedTs}` : ''}`);
+    return 0;
+}