tokenmaxing 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# tokenmaxing
+
+`tokenmaxing` is a local-only, read-only terminal summary for Claude Code and Codex usage — your AI usage, wrapped.
+
+It scans:
+
+- Claude Code: `~/.claude` (or `$CLAUDE_CONFIG_DIR`) for usage stats and transcripts, plus project `.claude` directories under your home directory.
+- Codex: `~/.codex` (or `$CODEX_HOME`).
+
+It renders, one section at a time:
+
+1. Total messages by source
+2. Per-month token usage
+3. Burn — local spend cache when present, otherwise a clearly marked list-price estimate
+4. All-time token usage
+5. Token usage summary
+6. Input/output token comparison
+7. Model token comparison
+8. Model standing by input + output tokens
+9. Most active time of day (messages per hour)
+10. Daily activity matrix (contribution-graph style)
+
+Every count and token figure comes from locally recorded data. The only estimated values are in the burn panel, marked with ≈.
+
+## Run
+
+```bash
+npx tokenmaxing
+```
+
+Or from a clone:
+
+```bash
+npm start
+```
+
+In a terminal the report reveals one section at a time, with a `[NN/total]` progress counter. Each section decodes in with a brief scramble-resolve animation.
+
+- `enter` / `space` / `→` — next section
+- `←` / `b` — replay the previous section
+- `a` — show all remaining sections
+- `q` / `ctrl-c` — quit
+
+Provider colors are categorical: Claude is orange, Codex is cyan, the combined total is amber — so any bar, model row, or table line maps to its source at a glance.
+
+Piped or redirected output prints everything at once without colors or animation.
+
+## Privacy
+
+The CLI reads local metadata and transcripts to compute usage, but the report does not print prompt text, model responses, tool outputs, credentials, or file contents. Nothing leaves your machine — there is no network call anywhere in the tool.

package/bin/ai-wrapped.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+runCli().catch((error) => {
+  console.error(`ai-wrapped failed: ${error?.message || error}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "tokenmaxing",
+  "version": "0.1.0",
+  "description": "Terminal AI usage wrapped summary for Claude Code and Codex.",
+  "author": "Kartik Gupta",
+  "type": "module",
+  "bin": {
+    "tokenmaxing": "bin/ai-wrapped.js"
+  },
+  "scripts": {
+    "start": "node ./bin/ai-wrapped.js"
+  },
+  "keywords": [
+    "codex",
+    "claude-code",
+    "usage",
+    "wrapped",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,91 @@
+import os from "node:os";
+import { scanClaude } from "./scanners/claude.js";
+import { scanCodex } from "./scanners/codex.js";
+import { combineReports } from "./metrics.js";
+import { renderReportBlocks, animateReveal, isColorEnabled } from "./report.js";
+
+export async function runCli() {
+  const reports = [
+    await scanClaude({
+      claudeHome: process.env.CLAUDE_CONFIG_DIR || `${os.homedir()}/.claude`,
+      scanRoot: os.homedir(),
+      maxScanDepth: 8,
+    }),
+    await scanCodex({
+      codexHome: process.env.CODEX_HOME || `${os.homedir()}/.codex`,
+    }),
+  ];
+
+  const combined = combineReports(reports);
+  const blocks = renderReportBlocks({ generatedAt: new Date().toISOString(), reports, combined });
+
+  const interactive = process.stdout.isTTY && process.stdin.isTTY;
+  if (!interactive) {
+    console.log(blocks.join("\n"));
+    return;
+  }
+
+  const animated = isColorEnabled();
+  const reveal = async (text) => {
+    if (animated) await animateReveal(text);
+    else console.log(text);
+  };
+
+  let index = 0;
+  await reveal(blocks[0]);
+
+  while (true) {
+    const atEnd = index === blocks.length - 1;
+    const action = await waitForStep(index + 1, blocks.length, atEnd);
+
+    if (action === "quit") break;
+    if (action === "all") {
+      if (index < blocks.length - 1) console.log(blocks.slice(index + 1).join("\n"));
+      break;
+    }
+    if (action === "next") {
+      if (atEnd) break;
+      index += 1;
+      await reveal(blocks[index]);
+    } else if (action === "back" && index > 0) {
+      index -= 1;
+      console.log(`\x1b[2m  ↑ replaying ${String(index + 1).padStart(2, "0")}/${blocks.length}\x1b[0m`);
+      await reveal(blocks[index]);
+    }
+  }
+}
+
+function waitForStep(current, total, atEnd) {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const progress = `\x1b[1m\x1b[38;2;255;138;0m[${String(current).padStart(2, "0")}/${total}]\x1b[0m`;
+    const forward = atEnd ? "↵ finish" : "↵ next";
+    const hints = `\x1b[2m${forward}   ← back   a all   q quit\x1b[0m`;
+    process.stdout.write(`  ${progress} \x1b[2m·\x1b[0m ${hints}`);
+
+    stdin.setRawMode(true);
+    stdin.resume();
+
+    const finish = (action) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      process.stdout.write("\r\x1b[2K");
+      resolve(action);
+    };
+
+    const onData = (buffer) => {
+      const sequence = buffer.toString();
+      if (sequence === "\x1b[C") return finish("next");
+      if (sequence === "\x1b[D") return finish("back");
+      for (const key of sequence) {
+        if (key === "\r" || key === "\n" || key === " ") return finish("next");
+        if (key === "q" || key === "Q" || key === "\x03") return finish("quit");
+        if (key === "a" || key === "A") return finish("all");
+        if (key === "b" || key === "B" || key === "p" || key === "P") return finish("back");
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}

package/src/metrics.js

@@ -0,0 +1,75 @@
+import { createEmptyReport, emptyTokens, addTokens, makeObjectMap } from "./utils.js";
+
+export function combineReports(reports) {
+  const combined = createEmptyReport("All AI", "all", "");
+  combined.sources = reports.map((report) => ({
+    key: report.key,
+    provider: report.provider,
+    root: report.root,
+    available: report.available,
+  }));
+
+  for (const report of reports) {
+    combined.available ||= report.available;
+    combined.sessionFiles += report.sessionFiles;
+    combined.historyEntries += report.historyEntries;
+    combined.projectConfigDirs += report.projectConfigDirs;
+    combined.totalSessions += report.totalSessions;
+    combined.totalMessages += report.totalMessages;
+    combined.knownSpendUSD += report.knownSpendUSD;
+    combined.unknownSpend ||= report.unknownSpend;
+    addTokens(combined.tokens, report.tokens);
+
+    if (report.firstSeen && (!combined.firstSeen || report.firstSeen < combined.firstSeen)) {
+      combined.firstSeen = report.firstSeen;
+    }
+    if (report.lastSeen && (!combined.lastSeen || report.lastSeen > combined.lastSeen)) {
+      combined.lastSeen = report.lastSeen;
+    }
+
+    for (const [day, messages] of Object.entries(report.dailyActivity || {})) {
+      combined.dailyActivity[day] = (combined.dailyActivity[day] || 0) + messages;
+    }
+    for (const [month, spend] of Object.entries(report.monthlySpendUSD)) {
+      combined.monthlySpendUSD[month] = (combined.monthlySpendUSD[month] || 0) + spend;
+    }
+    for (const [month, tokens] of Object.entries(report.monthlyTokens)) {
+      combined.monthlyTokens[month] ||= emptyTokens();
+      addTokens(combined.monthlyTokens[month], tokens);
+    }
+    for (const [model, usage] of Object.entries(report.modelUsage)) {
+      const key = `${report.key}:${model}`;
+      combined.modelUsage[key] ||= emptyTokens();
+      combined.modelUsage[key].provider = report.provider;
+      combined.modelUsage[key].model = model;
+      combined.modelUsage[key].costUSD = (combined.modelUsage[key].costUSD || 0) + (usage.costUSD || 0);
+      addTokens(combined.modelUsage[key], usage);
+    }
+    for (let hour = 0; hour < 24; hour += 1) {
+      combined.hourlyActivity[hour] += report.hourlyActivity[hour] || 0;
+    }
+    combined.notes.push(...report.notes.map((note) => `${report.provider}: ${note}`));
+  }
+
+  finalizeReport(combined);
+  return combined;
+}
+
+export function finalizeReport(report) {
+  report.dailyActivity = makeObjectMap(report.dailyActivity || {});
+  report.monthlySpendUSD = makeObjectMap(report.monthlySpendUSD);
+  report.monthlyTokens = makeObjectMap(report.monthlyTokens);
+  report.modelUsage = makeObjectMap(report.modelUsage);
+
+  const favorite = Object.values(report.modelUsage)
+    .map((usage) => ({
+      provider: usage.provider || report.provider,
+      model: usage.model || "unknown",
+      score: (usage.input || 0) + (usage.output || 0),
+      total: usage.total || 0,
+    }))
+    .sort((a, b) => b.score - a.score)[0];
+
+  report.favoriteModel = favorite || null;
+  return report;
+}

package/src/pricing.js

@@ -0,0 +1,68 @@
+// Public list prices in USD per 1M tokens. cacheWrite is the 5m prompt-cache
+// write rate where the provider charges one; OpenAI does not bill cache writes.
+// Reasoning tokens are billed inside output tokens by both providers, so they
+// are intentionally not priced separately.
+const PRICING_TABLE = [
+  // anthropic
+  { prefix: "claude-opus-4-5", rates: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 } },
+  { prefix: "claude-opus-4-6", rates: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 } },
+  { prefix: "claude-opus-4-7", rates: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 } },
+  { prefix: "claude-opus-4-8", rates: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 } },
+  { prefix: "claude-opus", rates: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 } },
+  { prefix: "claude-sonnet", rates: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 } },
+  { prefix: "claude-haiku-4-5", rates: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 } },
+  { prefix: "claude-haiku", rates: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 } },
+  // openai
+  { prefix: "gpt-5-mini", rates: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 } },
+  { prefix: "gpt-5-nano", rates: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 } },
+  { prefix: "gpt-5", rates: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 0 } },
+  { prefix: "gpt-4.1-mini", rates: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0 } },
+  { prefix: "gpt-4.1", rates: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 } },
+  { prefix: "gpt-4o-mini", rates: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0 } },
+  { prefix: "gpt-4o", rates: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 0 } },
+  { prefix: "o4-mini", rates: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 0 } },
+  { prefix: "o3", rates: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 0 } },
+  { prefix: "codex-mini", rates: { input: 1.5, output: 6, cacheRead: 0.375, cacheWrite: 0 } },
+].sort((a, b) => b.prefix.length - a.prefix.length);
+
+export function priceForModel(model) {
+  const normalized = String(model || "")
+    .toLowerCase()
+    .replace(/\./g, "-")
+    .trim();
+  for (const entry of PRICING_TABLE) {
+    if (normalized.startsWith(entry.prefix.replace(/\./g, "-"))) return entry.rates;
+  }
+  return null;
+}
+
+export function estimateTokensCostUSD(tokens, rates) {
+  if (!rates) return null;
+  return (
+    ((tokens.input || 0) * rates.input +
+      (tokens.output || 0) * rates.output +
+      (tokens.cacheRead || 0) * rates.cacheRead +
+      (tokens.cacheCreation || 0) * rates.cacheWrite) /
+    1_000_000
+  );
+}
+
+export function estimateModelCosts(modelUsage) {
+  const priced = [];
+  const unpriced = [];
+  let totalUSD = 0;
+
+  for (const usage of Object.values(modelUsage || {})) {
+    const rates = priceForModel(usage.model);
+    const costUSD = estimateTokensCostUSD(usage, rates);
+    if (costUSD === null) {
+      unpriced.push(usage.model || "unknown");
+      continue;
+    }
+    totalUSD += costUSD;
+    priced.push({ usage, rates, costUSD });
+  }
+
+  priced.sort((a, b) => b.costUSD - a.costUSD);
+  return { priced, unpriced, totalUSD };
+}