tokenmaxxing-cli 0.1.0

package/dist/parsers/codex.js

@@ -0,0 +1,201 @@
+import { readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { BucketAccumulator, hourOf } from '../bucket.js';
+import { walkFiles } from '../fsutil.js';
+import { parseLine, scanLines } from '../lines.js';
+import { num } from './context.js';
+const isRollout = (n) => n.startsWith('rollout-') && n.endsWith('.jsonl');
+/** Top-level `type` (and event_msg payload.type) sit in the first bytes of every Codex line. */
+const HEAD = 320;
+const NEEDLES = ['"token_usage_record"', '"turn_context"', '"session_meta"', '"token_count"'].map((s) => Buffer.from(s));
+const RAW_FIELDS = [
+    'input_tokens', 'cached_input_tokens', 'cache_write_input_tokens', 'output_tokens', 'reasoning_output_tokens',
+];
+function raw(u) {
+    return {
+        input_tokens: num(u?.input_tokens),
+        cached_input_tokens: num(u?.cached_input_tokens),
+        cache_write_input_tokens: num(u?.cache_write_input_tokens),
+        output_tokens: num(u?.output_tokens),
+        reasoning_output_tokens: num(u?.reasoning_output_tokens),
+    };
+}
+/** Codex `input_tokens` includes `cached_input_tokens`; `output_tokens` already includes reasoning. */
+export function codexUsage(r) {
+    return {
+        input: Math.max(0, r.input_tokens - r.cached_input_tokens),
+        cache_read: r.cached_input_tokens,
+        cache_write_5m: r.cache_write_input_tokens,
+        cache_write_1h: 0,
+        output: r.output_tokens,
+        reasoning: r.reasoning_output_tokens,
+    };
+}
+const isZeroRaw = (r) => RAW_FIELDS.every((f) => r[f] === 0);
+/** rollout files keyed by basename (so a session moved into archived_sessions/ is not re-counted). */
+export async function codexFiles(roots) {
+    const found = new Map();
+    for (const root of roots) {
+        const list = await walkFiles(join(root, 'sessions'), isRollout);
+        try {
+            const archived = join(root, 'archived_sessions');
+            for (const n of (await readdir(archived)).sort())
+                if (isRollout(n))
+                    list.push(join(archived, n));
+        }
+        catch {
+            /* no archived_sessions */
+        }
+        for (const f of list)
+            if (!found.has(basename(f)))
+                found.set(basename(f), f);
+    }
+    return found;
+}
+export async function parse(ctx) {
+    const { cursor, dedup, acc, stats } = ctx;
+    const files = await codexFiles(ctx.paths);
+    for (const [key, file] of files) {
+        stats.filesSeen++;
+        let st;
+        try {
+            st = await stat(file);
+        }
+        catch {
+            continue;
+        }
+        const prev = cursor.files[key];
+        if (prev && prev.size === st.size && prev.mtimeMs === st.mtimeMs)
+            continue;
+        stats.filesChanged++;
+        const shrank = !!prev && st.size < prev.offset;
+        const base = shrank ? undefined : prev;
+        const start = base?.offset ?? 0;
+        let model = base?.model;
+        let root = base?.root;
+        let cum = base?.cum ? raw(fromUsageCursor(base.cum)) : undefined;
+        let sawRecords = !!base?.records;
+        const recAcc = new BucketAccumulator();
+        const fbAcc = new BucketAccumulator();
+        const modelNow = () => model ?? 'unknown-codex';
+        const handle = (obj) => {
+            if (!obj || typeof obj !== 'object')
+                return;
+            const p = obj.payload;
+            switch (obj.type) {
+                case 'session_meta':
+                    if (!model && typeof p?.model === 'string' && p.model)
+                        model = p.model;
+                    return;
+                case 'turn_context': {
+                    if (typeof p?.model === 'string' && p.model)
+                        model = p.model;
+                    const r = p?.root_turn_id;
+                    if (typeof r === 'string' && r && r !== root) {
+                        root = r;
+                        const h = hourOf(obj.timestamp);
+                        if (h)
+                            acc.addConversation(h, 'codex', modelNow());
+                    }
+                    return;
+                }
+                case 'token_usage_record': {
+                    sawRecords = true;
+                    if (!p?.usage)
+                        return;
+                    const rid = p.response_id;
+                    if (typeof rid === 'string' && rid && !dedup.add(rid))
+                        return;
+                    const r = raw(p.usage);
+                    if (isZeroRaw(r))
+                        return;
+                    const h = hourOf(obj.timestamp);
+                    if (!h) {
+                        stats.badLines++;
+                        return;
+                    }
+                    recAcc.addUsage(h, 'codex', modelNow(), codexUsage(r));
+                    return;
+                }
+                case 'event_msg': {
+                    if (p?.type !== 'token_count' || !p.info)
+                        return;
+                    const tot = p.info.total_token_usage;
+                    if (!tot)
+                        return;
+                    const now = raw(tot);
+                    let delta;
+                    if (!cum)
+                        delta = now;
+                    else if (RAW_FIELDS.every((f) => now[f] >= cum[f])) {
+                        delta = raw({});
+                        for (const f of RAW_FIELDS)
+                            delta[f] = now[f] - cum[f];
+                    }
+                    else {
+                        // Cumulative counter went backwards (session reset): count this response only.
+                        delta = p.info.last_token_usage ? raw(p.info.last_token_usage) : now;
+                    }
+                    cum = now;
+                    if (isZeroRaw(delta))
+                        return;
+                    const h = hourOf(obj.timestamp);
+                    if (h)
+                        fbAcc.addUsage(h, 'codex', modelNow(), codexUsage(delta));
+                    return;
+                }
+            }
+        };
+        const onLine = (line) => {
+            const head = line.subarray(0, HEAD);
+            if (!NEEDLES.some((n) => head.indexOf(n) !== -1))
+                return;
+            const obj = parseLine(line);
+            if (obj === undefined) {
+                stats.badLines++;
+                return;
+            }
+            handle(obj);
+        };
+        let end = start;
+        try {
+            const res = await scanLines(file, start, st.size, onLine);
+            end = res.end;
+            stats.bytesRead += st.size - start;
+            if (res.tail) {
+                const obj = parseLine(res.tail);
+                if (obj !== undefined) {
+                    handle(obj);
+                    end = st.size;
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+        // Never mix paths within one file: token_usage_record wins whenever the file has any.
+        for (const b of (sawRecords ? recAcc : fbAcc).rows()) {
+            acc.addUsage(b.ts, 'codex', b.model, b, b.requests);
+        }
+        const next = { size: st.size, mtimeMs: st.mtimeMs, offset: end };
+        if (model)
+            next.model = model;
+        if (root)
+            next.root = root;
+        if (sawRecords)
+            next.records = true;
+        if (cum)
+            next.cum = toUsageCursor(cum);
+        cursor.files[key] = next;
+    }
+    return acc.rows();
+}
+// The cursor stores the raw cumulative counters under Usage-like names to keep cursors.json compact.
+function toUsageCursor(r) {
+    return { i: r.input_tokens, c: r.cached_input_tokens, w: r.cache_write_input_tokens, o: r.output_tokens, r: r.reasoning_output_tokens };
+}
+function fromUsageCursor(c) {
+    return {
+        input_tokens: c.i, cached_input_tokens: c.c, cache_write_input_tokens: c.w, output_tokens: c.o, reasoning_output_tokens: c.r,
+    };
+}

package/dist/parsers/context.js

@@ -0,0 +1,9 @@
+export const DEDUP_LIMIT = 200_000;
+/** Recent per-key contributions kept in cursors.json for cross-sync replacement. */
+export const RECENT_LIMIT = 10_000;
+export function newStats() {
+    return { filesSeen: 0, filesChanged: 0, bytesRead: 0, badLines: 0 };
+}
+export function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0;
+}

package/dist/parsers/cursor.js

@@ -0,0 +1,11 @@
+/**
+ * Cursor: activity only, no tokens.
+ *
+ * ~/.cursor/ai-tracking/ai-code-tracking.db has no token counts (verified), so v1 reads nothing from it;
+ * `init` reports Cursor as detected but excluded from totals. No sqlite dependency is added.
+ *
+ * TODO: if Cursor ever writes local token usage, parse it here (one file, fixture-tested like the others).
+ */
+export async function parse(_ctx) {
+    return [];
+}

package/dist/parsers/gemini.js

@@ -0,0 +1,110 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hourOf } from '../bucket.js';
+import { num } from './context.js';
+/** Gemini CLI chat files: ~/.gemini/tmp/<project-hash>/chats/*.json */
+export async function geminiFiles(roots) {
+    const out = [];
+    for (const root of roots) {
+        const tmp = join(root, 'tmp');
+        let projects = [];
+        try {
+            projects = await readdir(tmp);
+        }
+        catch {
+            continue;
+        }
+        for (const p of projects.sort()) {
+            const chats = join(tmp, p, 'chats');
+            try {
+                for (const n of (await readdir(chats)).sort())
+                    if (n.endsWith('.json'))
+                        out.push(join(chats, n));
+            }
+            catch {
+                /* not a project dir */
+            }
+        }
+    }
+    return out;
+}
+/** input excludes cached; tool-use and thought tokens are billed as output (reasoning kept for info). */
+export function geminiUsage(t) {
+    const input = num(t?.input);
+    const cached = num(t?.cached);
+    const output = num(t?.output);
+    const tool = num(t?.tool);
+    const thoughts = num(t?.thoughts);
+    const u = {
+        input: Math.max(0, input - cached),
+        cache_read: cached,
+        cache_write_5m: 0,
+        cache_write_1h: 0,
+        output: output + tool + thoughts,
+        reasoning: thoughts,
+    };
+    return u.input + u.cache_read + u.output === 0 ? null : u;
+}
+export async function parse(ctx) {
+    const { cursor, acc, stats } = ctx;
+    for (const file of await geminiFiles(ctx.paths)) {
+        stats.filesSeen++;
+        let st;
+        try {
+            st = await stat(file);
+        }
+        catch {
+            continue;
+        }
+        const prev = cursor.files[file];
+        if (prev && prev.size === st.size && prev.mtimeMs === st.mtimeMs)
+            continue;
+        stats.filesChanged++;
+        let doc;
+        try {
+            // Gemini writes one JSON document per chat (not JSONL), so the file is parsed whole.
+            doc = JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch {
+            stats.badLines++;
+            continue; // possibly mid-write; cursor untouched so we retry next sync
+        }
+        stats.bytesRead += st.size;
+        const messages = Array.isArray(doc?.messages) ? doc.messages : [];
+        let from = prev?.count ?? 0;
+        if (messages.length < from)
+            from = 0; // file shrank / rewritten
+        const fallbackTs = doc?.lastUpdated ?? doc?.startTime ?? st.mtimeMs;
+        let pending = [];
+        let lastModel = prev?.model;
+        for (let i = from; i < messages.length; i++) {
+            const m = messages[i];
+            if (!m || typeof m !== 'object') {
+                stats.badLines++;
+                continue;
+            }
+            const role = m.role ?? m.type;
+            const hour = hourOf(m.timestamp ?? fallbackTs);
+            if (!hour)
+                continue;
+            if (role === 'user') {
+                pending.push(hour);
+                continue;
+            }
+            const u = m.tokens ? geminiUsage(m.tokens) : null;
+            if (!u)
+                continue;
+            const model = typeof m.model === 'string' && m.model ? m.model : 'gemini-unknown';
+            lastModel = model;
+            acc.addUsage(hour, 'gemini', model, u);
+            for (const h of pending)
+                acc.addConversation(h, 'gemini', model);
+            pending = [];
+        }
+        // Prompts with no response yet are attributed to the last model seen (or gemini-unknown).
+        for (const h of pending)
+            acc.addConversation(h, 'gemini', lastModel ?? 'gemini-unknown');
+        cursor.files[file] = { size: st.size, mtimeMs: st.mtimeMs, offset: st.size, count: messages.length, ...(lastModel ? { model: lastModel } : {}) };
+    }
+    return acc.rows();
+}

package/dist/paths.js

@@ -0,0 +1,32 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function home() {
+    return process.env.HOME || homedir();
+}
+export function tmxHome() {
+    return process.env.TOKENMAXXING_HOME || join(home(), '.tokenmaxxing');
+}
+export const files = {
+    config: () => join(tmxHome(), 'config.json'),
+    buckets: () => join(tmxHome(), 'buckets.jsonl'),
+    cursors: () => join(tmxHome(), 'cursors.json'),
+    lock: () => join(tmxHome(), 'sync.lock'),
+    cacheDir: () => join(tmxHome(), 'cache'),
+};
+/** Claude Code roots: CLAUDE_CONFIG_DIR (comma separated) else ~/.config/claude and ~/.claude. */
+export function claudeCandidateRoots() {
+    const env = process.env.CLAUDE_CONFIG_DIR;
+    if (env && env.trim()) {
+        return env.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    return [join(home(), '.config', 'claude'), join(home(), '.claude')];
+}
+export function codexHome() {
+    return process.env.CODEX_HOME || join(home(), '.codex');
+}
+export function geminiHome() {
+    return join(home(), '.gemini');
+}
+export function cursorTrackingDb() {
+    return join(home(), '.cursor', 'ai-tracking', 'ai-code-tracking.db');
+}

package/dist/period.js

@@ -0,0 +1,37 @@
+import { localDate } from './format.js';
+const DAY = 86_400_000;
+/**
+ * `--since 7d|30d|YYYY-MM-DD` (default 30d). Days are local calendar days, matching ccusage:
+ * "30d" on 2026-09-22 covers 2026-08-23 00:00 local → now.
+ */
+export function parsePeriod(since, now = new Date()) {
+    const s = (since ?? '30d').trim();
+    const todayMidnight = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    let start;
+    let days;
+    let label;
+    const rel = /^(\d+)d$/i.exec(s);
+    const abs = /^(\d{4})-?(\d{2})-?(\d{2})$/.exec(s);
+    if (rel) {
+        days = Number(rel[1]);
+        if (!(days > 0))
+            throw new Error(`--since must be positive: ${s}`);
+        start = new Date(todayMidnight.getFullYear(), todayMidnight.getMonth(), todayMidnight.getDate() - days);
+        label = `last ${days} day${days === 1 ? '' : 's'}`;
+    }
+    else if (abs) {
+        start = new Date(Number(abs[1]), Number(abs[2]) - 1, Number(abs[3]));
+        if (Number.isNaN(start.getTime()) || start > now)
+            throw new Error(`invalid --since date: ${s}`);
+        days = Math.max(1, Math.round((todayMidnight.getTime() - start.getTime()) / DAY));
+        label = `since ${localDate(start)}`;
+    }
+    else {
+        throw new Error(`--since expects 7d, 30d or YYYY-MM-DD (got "${s}")`);
+    }
+    return { start, end: now, sinceDate: localDate(start), untilDate: localDate(now), days, label };
+}
+export function inPeriod(ts, p) {
+    const t = Date.parse(ts);
+    return t >= p.start.getTime() && t < p.end.getTime();
+}

package/dist/plans.js

@@ -0,0 +1,169 @@
+import { readFileSync } from 'node:fs';
+import { PROVIDER_SOURCE } from './types.js';
+let plans;
+export function planTable() {
+    plans ??= JSON.parse(readFileSync(new URL('./plans.json', import.meta.url), 'utf8'));
+    return plans;
+}
+export const PROVIDERS = Object.keys(PROVIDER_SOURCE);
+export function isProvider(p) {
+    return PROVIDERS.includes(p);
+}
+export function planPrice(provider, plan) {
+    const t = planTable()[provider];
+    return t && Object.prototype.hasOwnProperty.call(t, plan) ? t[plan] : undefined;
+}
+export function sourceFor(provider) {
+    return PROVIDER_SOURCE[provider];
+}
+export const MONTH_DAYS = 30.4375;
+/** API-equivalent cost ÷ plan cost prorated to the period length. */
+export function roi(apiCost, monthlyPrice, days) {
+    const prorated = (monthlyPrice * days) / MONTH_DAYS;
+    return prorated > 0 ? apiCost / prorated : 0;
+}
+// ------------------------------------------------------------------ plan lines
+export const CUSTOM = 'custom';
+export const QTY_MAX = 99;
+export const LABEL_MAX = 40;
+export const CUSTOM_MIN = 0.01;
+export const CUSTOM_MAX = 10000;
+export const isQty = (n) => typeof n === 'number' && Number.isInteger(n) && n >= 1 && n <= QTY_MAX;
+export function cleanLabel(s) {
+    const t = typeof s === 'string' ? s.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, LABEL_MAX).trim() : '';
+    return t || 'Custom';
+}
+/** Custom monthly amount rounded to cents, or undefined when out of range. */
+export function cleanMonthly(n) {
+    if (typeof n !== 'number' || !Number.isFinite(n))
+        return undefined;
+    const r = Math.round(n * 100) / 100;
+    return r >= CUSTOM_MIN && r <= CUSTOM_MAX ? r : undefined;
+}
+function lineOf(provider, raw) {
+    if (typeof raw === 'string')
+        return planPrice(provider, raw) === undefined ? undefined : { plan: raw, qty: 1 };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    const qty = o.qty === undefined ? 1 : o.qty;
+    if (!isQty(qty) || typeof o.plan !== 'string')
+        return undefined;
+    if (o.plan === CUSTOM) {
+        const monthly = cleanMonthly(o.monthly);
+        return monthly === undefined ? undefined : { plan: CUSTOM, label: cleanLabel(o.label), monthly, qty };
+    }
+    return planPrice(provider, o.plan) === undefined ? undefined : { plan: o.plan, qty };
+}
+const lineKey = (l) => (l.plan === CUSTOM ? `${CUSTOM}\u0000${l.label}\u0000${l.monthly}` : l.plan);
+/**
+ * One provider's lines from either stored shape: the legacy string (`"max-20x"`) or a list of
+ * line objects. Unknown plans and bad quantities are dropped; duplicates merge by summing qty.
+ */
+export function normalizeLines(provider, raw) {
+    const items = Array.isArray(raw) ? raw : raw === undefined || raw === null ? [] : [raw];
+    const out = [];
+    const byKey = new Map();
+    for (const item of items) {
+        const l = lineOf(provider, item);
+        if (!l)
+            continue;
+        const prev = byKey.get(lineKey(l));
+        if (prev)
+            prev.qty = Math.min(QTY_MAX, prev.qty + l.qty);
+        else {
+            byKey.set(lineKey(l), l);
+            out.push(l);
+        }
+    }
+    return out;
+}
+/** Every provider's lines, from either shape. Unknown providers and empty providers are dropped. */
+export function normalizePlans(raw) {
+    const out = {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return out;
+    for (const [provider, v] of Object.entries(raw)) {
+        if (!isProvider(provider))
+            continue;
+        const lines = normalizeLines(provider, v);
+        if (lines.length)
+            out[provider] = lines;
+    }
+    return out;
+}
+/** Monthly price of one seat of a line. */
+export function unitPrice(provider, l) {
+    return l.plan === CUSTOM ? (l.monthly ?? 0) : (planPrice(provider, l.plan) ?? 0);
+}
+const cents = (n) => Math.round(n * 100) / 100;
+/** Σ unit price × qty for one provider. */
+export function providerMonthly(provider, lines) {
+    return cents(lines.reduce((s, l) => s + unitPrice(provider, l) * l.qty, 0));
+}
+/** Σ over providers. */
+export function plansMonthly(p) {
+    return cents(PROVIDERS.reduce((s, prov) => s + providerMonthly(prov, p[prov] ?? []), 0));
+}
+/** `max-20x` or the custom line's label. */
+export const lineName = (l) => (l.plan === CUSTOM ? (l.label ?? 'Custom') : l.plan);
+/** "5× max-20x + 1× pro" */
+export function describeLines(lines) {
+    return lines.map((l) => `${l.qty}× ${lineName(l)}`).join(' + ');
+}
+/** `x5`, `X5` or `×5` → 5; anything else → undefined. */
+export function parseQtyToken(s) {
+    const m = /^[x×](\d{1,3})$/i.exec(s);
+    return m ? Number(m[1]) : undefined;
+}
+/**
+ * The plan part of `plan set|add <provider> <plan> [xN]` and
+ * `plan set|add <provider> custom <monthly> [label…] [xN]`. `--qty N` may stand in for `xN`.
+ * Returns the line, or a message saying what is wrong.
+ */
+export function parsePlanSpec(provider, args, qtyFlag) {
+    const [plan, ...rest] = args;
+    let qty;
+    const words = [];
+    for (const a of rest) {
+        const q = parseQtyToken(a);
+        if (q === undefined)
+            words.push(a);
+        else if (qty !== undefined)
+            return 'give the quantity once';
+        else
+            qty = q;
+    }
+    if (qtyFlag !== undefined) {
+        if (qty !== undefined)
+            return 'give the quantity once (xN or --qty N)';
+        qty = /^\d{1,3}$/.test(qtyFlag) ? Number(qtyFlag) : NaN;
+    }
+    qty ??= 1;
+    if (!isQty(qty))
+        return `quantity must be a whole number from 1 to ${QTY_MAX}`;
+    const t = planTable()[provider];
+    if (!plan || (plan !== CUSTOM && planPrice(provider, plan) === undefined)) {
+        return `plan for ${provider} must be one of: ${Object.keys(t).join(', ')}, or custom <monthly> [label]`;
+    }
+    if (plan === CUSTOM) {
+        const [amount, ...label] = words;
+        const monthly = amount !== undefined && /^\$?\d+(\.\d+)?$/.test(amount) ? cleanMonthly(Number(amount.replace('$', ''))) : undefined;
+        if (monthly === undefined)
+            return `custom needs a monthly amount from ${CUSTOM_MIN} to ${CUSTOM_MAX}, e.g. plan add ${provider} custom 100 "Promo"`;
+        const text = label.join(' ').trim();
+        if (text.length > LABEL_MAX)
+            return `custom label must be at most ${LABEL_MAX} characters`;
+        return { plan: CUSTOM, label: cleanLabel(text), monthly, qty };
+    }
+    if (words.length)
+        return `unexpected argument: ${words[0]}`;
+    return { plan, qty };
+}
+/** Adds a line to a provider's lines, merging with an existing line for the same plan. */
+export function addLine(lines, line) {
+    const prev = lines.find((l) => lineKey(l) === lineKey(line));
+    if (prev && prev.qty + line.qty > QTY_MAX)
+        return `${lineName(line)} would reach ${prev.qty + line.qty}; the most is ${QTY_MAX}`;
+    return prev ? lines.map((l) => (l === prev ? { ...l, qty: l.qty + line.qty } : l)) : [...lines, line];
+}

package/dist/plans.json

@@ -0,0 +1,6 @@
+{
+  "claude": { "pro": 20, "max-5x": 100, "max-20x": 200, "team-standard": 25, "team-premium": 125 },
+  "openai": { "go": 8, "plus": 20, "pro-100": 100, "pro": 200, "business": 25 },
+  "cursor": { "pro": 20, "pro-plus": 60, "ultra": 200, "teams": 40 },
+  "google": { "ai-plus": 4.99, "ai-pro": 19.99, "ai-ultra-100": 99.99, "ai-ultra": 199.99 }
+}