llm-usage-dashboard 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# AI Usage Dashboard
+
+一個在 **Windows** 本機執行的桌面 App,一次看到 **Codex (OpenAI)** 與 **Claude Code (Anthropic)** 的訂閱用量、剩餘額度、重置時間,以及各專案的 token 消耗與預估花費。
+
+開機自動常駐於系統匣 (tray),監看本機資料檔變化即時更新。
+
+---
+
+## 它顯示什麼
+
+| 區塊 | 內容 |
+|------|------|
+| 總覽 | 本月預估花費、本月總 tokens、累計花費 |
+| Codex 卡片 | **5 小時 / 每週額度**(官方精確 `used_percent` + 重置倒數)、方案(plus)、今日/本月 tokens、本月花費估算 |
+| Claude 卡片 | **5 小時區塊 / 近 7 天**用量(依 token 記錄重建)、方案(max)、今日/本月 tokens、本月花費估算 |
+| 近 14 天圖 | 每日 Codex/Claude tokens 堆疊長條 |
+| 各專案用量 | 每個專案(依 `cwd`)的來源、累計/本月 tokens、本月花費、最後活動時間 |
+
+### 資料來源(全部讀本機檔案,不連網)
+
+- **Codex** — `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+  - `token_count` 事件含 `total_token_usage` 與 **`rate_limits`**(`primary`=5h、`secondary`=weekly,含 `used_percent`、`resets_at`)→ **額度為官方精確值**。
+- **Claude Code** — `~/.claude/projects/<專案>/<session>.jsonl`
+  - 每筆 assistant 記錄的 `message.usage`(input/output/cache),依 `requestId:messageId` 去重。
+  - Anthropic **本地不儲存官方額度數字**,故 5h/每週為依用量重建的估算視窗(ccusage 式 5 小時滾動區塊)。
+
+> 同時涵蓋 CLI 與桌面版 —— 兩者共用同一份本機檔案。
+
+---
+
+## 一行安裝(最友善,給有 Node 的人)
+
+會用到這個 dashboard 的人通常本來就裝了 Node(因為在用 Codex / Claude Code),所以最方便的方式就是發佈到 npm,之後任何人:
+
+```powershell
+npx llm-usage-dashboard        # 不安裝,直接跑(首次會下載 Electron)
+# 或裝成全域指令
+npm i -g llm-usage-dashboard
+llm-usage-dashboard
+```
+
+> 發佈者(你)只需做一次:`npm login` 後 `npm publish`。改版只要把 `version` +1 再 `npm publish`。
+> 套件已設定好 `bin`(`bin/cli.js`)、`files` 與把 `electron` 列為正式相依,使用者裝完即可一行啟動。
+
+## 從原始碼執行
+
+需求:Node.js(已驗證 v22)。
+
+```powershell
+cd D:\aiworkspace\ai-usage-dashboard
+npm install      # 只需一次,安裝 Electron
+npm start        # 啟動 App
+```
+
+啟動後:
+- 主視窗開啟;關閉視窗會**縮到系統匣**(不結束)。
+- 系統匣圖示:左鍵開視窗、右鍵選單(立即重新整理、開機自動啟動開關、開啟資料夾、結束)。
+
+### 快速驗證資料(不開視窗)
+
+```powershell
+npm run probe
+```
+
+直接在終端機印出 Codex/Claude 的額度、tokens、花費與各專案彙總。
+
+---
+
+## 開機自動啟動
+
+於系統匣選單或視窗右上角勾選「開機自動啟動」即可。底層使用 Electron `app.setLoginItemSettings({ openAtLogin, args:['--hidden'] })`;以 `--hidden` 啟動時不開視窗,只常駐系統匣。
+
+---
+
+## 打包成安裝檔(選用)
+
+```powershell
+npm run dist     # 透過 electron-builder 產生 Windows 安裝檔 (NSIS)
+```
+
+---
+
+## 花費估算說明
+
+訂閱制不是按 token 計費,所以金額是**參考值**。單價表在 `src/main/pricing.js`(USD / 1M tokens)。
+可在 `assets/pricing.json` 放覆寫值(格式同 `DEFAULT_PRICES_PER_M`,以模型名子字串比對),不需改程式。
+
+---
+
+## 架構
+
+```
+src/
+  main/
+    main.js              Electron 主程序:視窗 / 系統匣 / 自動啟動 / fs.watch / IPC
+    paths.js             解析 ~/.codex、~/.claude 路徑;正規化專案 cwd
+    pricing.js           模型單價表 + 花費計算
+    aggregate.js         5h / 週 / 月 視窗、各專案彙總、每日序列、花費
+    probe.js             不需 Electron 的命令列驗證工具
+    collectors/
+      jsonl.js           串流讀取 .jsonl
+      codex.js           Codex 解析(token + 官方 rate_limits)
+      claude.js          Claude Code 解析(去重 + token)
+  preload.js             contextBridge 安全橋接
+  renderer/              儀表板 UI(index.html / styles.css / app.js)
+assets/                  圖示(genicon.js 產生)
+```
+
+更新機制:`fs.watch`(遞迴)監看兩個資料夾,變更後 1.5 秒去抖動重掃(即時);另**每 5 分鐘**自動拉取一次作為保底,畫面右上角顯示下次更新倒數。
+
+---
+
+## 已知限制
+
+- Claude 的 5h/每週為**重建估算**,非官方配額%(Anthropic 未在本機儲存配額數字)。Codex 則為官方精確值。
+- 「每月」兩者皆無官方配額,為當月日曆彙總,屬參考。
+- 花費為估算,非實際帳單。

package/assets/genicon.js

@@ -0,0 +1,90 @@
+'use strict';
+// Generates assets/icon.png (256x256) and assets/tray.png (32x32) without any
+// native deps — a small PNG encoder over a hand-drawn RGBA gauge motif.
+const zlib = require('zlib');
+const fs = require('fs');
+const path = require('path');
+
+function crc32(buf) {
+  let c = ~0;
+  for (let i = 0; i < buf.length; i++) {
+    c ^= buf[i];
+    for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xEDB88320 & -(c & 1));
+  }
+  return ~c >>> 0;
+}
+function chunk(type, data) {
+  const len = Buffer.alloc(4); len.writeUInt32BE(data.length, 0);
+  const t = Buffer.from(type, 'ascii');
+  const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(Buffer.concat([t, data])), 0);
+  return Buffer.concat([len, t, data, crc]);
+}
+function encodePNG(width, height, rgba) {
+  const sig = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; ihdr[9] = 6; // 8-bit, RGBA
+  const raw = Buffer.alloc((width * 4 + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (width * 4 + 1)] = 0;
+    rgba.copy(raw, y * (width * 4 + 1) + 1, y * width * 4, (y + 1) * width * 4);
+  }
+  const idat = zlib.deflateSync(raw, { level: 9 });
+  return Buffer.concat([sig, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', Buffer.alloc(0))]);
+}
+
+function draw(size) {
+  const buf = Buffer.alloc(size * size * 4);
+  const cx = size / 2, cy = size / 2;
+  const R = size * 0.40, ring = size * 0.11;
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const i = (y * size + x) * 4;
+      const dx = x + 0.5 - cx, dy = y + 0.5 - cy;
+      const d = Math.sqrt(dx * dx + dy * dy);
+      let r = 0, g = 0, b = 0, a = 0;
+      // rounded dark background
+      const bgR = size * 0.46;
+      if (d <= bgR) { r = 24; g = 27; b = 38; a = 255; }
+      // gauge ring: angle from -210deg..30deg, two-tone (codex green / claude orange)
+      if (d <= R + ring / 2 && d >= R - ring / 2) {
+        let ang = Math.atan2(dy, dx) * 180 / Math.PI; // -180..180
+        let t = (ang + 210) % 360; // 0 at start
+        if (t >= 0 && t <= 240) {
+          if (t < 120) { r = 52; g = 211; b = 153; } // teal/green
+          else { r = 251; g = 146; b = 60; }         // orange
+          a = 255;
+        }
+      }
+      // center dot
+      if (d <= size * 0.12) { r = 96; g = 165; b = 250; a = 255; }
+      buf[i] = r; buf[i + 1] = g; buf[i + 2] = b; buf[i + 3] = a;
+    }
+  }
+  return buf;
+}
+
+// Wrap a 256x256 PNG inside an .ico container (valid for modern Windows).
+function encodeICO(png) {
+  const header = Buffer.alloc(6);
+  header.writeUInt16LE(0, 0); // reserved
+  header.writeUInt16LE(1, 2); // type = icon
+  header.writeUInt16LE(1, 4); // image count
+  const entry = Buffer.alloc(16);
+  entry[0] = 0; // width 0 => 256
+  entry[1] = 0; // height 0 => 256
+  entry[2] = 0; // palette
+  entry[3] = 0; // reserved
+  entry.writeUInt16LE(1, 4);  // color planes
+  entry.writeUInt16LE(32, 6); // bits per pixel
+  entry.writeUInt32LE(png.length, 8); // size of PNG data
+  entry.writeUInt32LE(6 + 16, 12);    // offset to PNG data
+  return Buffer.concat([header, entry, png]);
+}
+
+const outDir = __dirname;
+const png256 = encodePNG(256, 256, draw(256));
+fs.writeFileSync(path.join(outDir, 'icon.png'), png256);
+fs.writeFileSync(path.join(outDir, 'tray.png'), encodePNG(32, 32, draw(32)));
+fs.writeFileSync(path.join(outDir, 'icon.ico'), encodeICO(png256));
+console.log('icons written (png + tray + ico)');

package/assets/pricing.json.example

@@ -0,0 +1,7 @@
+{
+  "_comment": "把這個檔複製成 pricing.json 即可覆寫預設模型單價。單位:USD / 1,000,000 tokens。key 以模型 id 子字串比對,最長相符者優先。只需列出想覆寫的項目。",
+  "gpt-5": { "input": 1.25, "output": 10, "cacheWrite": 1.25, "cacheRead": 0.125 },
+  "codex": { "input": 1.25, "output": 10, "cacheWrite": 1.25, "cacheRead": 0.125 },
+  "claude-opus": { "input": 15, "output": 75, "cacheWrite": 18.75, "cacheRead": 1.5 },
+  "claude-sonnet": { "input": 3, "output": 15, "cacheWrite": 3.75, "cacheRead": 0.3 }
+}

package/bin/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+// Launcher so the app can be run via `npx ai-usage-dashboard` or, after
+// `npm i -g ai-usage-dashboard`, simply `ai-usage-dashboard`.
+// `require('electron')` resolves to the Electron binary path when run from Node.
+const { spawn } = require('child_process');
+const path = require('path');
+
+let electronPath;
+try {
+  electronPath = require('electron');
+} catch (e) {
+  console.error('找不到 Electron。請先安裝:npm i -g ai-usage-dashboard(或在專案內 npm install)。');
+  process.exit(1);
+}
+
+const appDir = path.join(__dirname, '..');
+const child = spawn(electronPath, [appDir, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  windowsHide: false,
+});
+child.on('close', (code) => process.exit(code == null ? 0 : code));
+child.on('error', (err) => { console.error('啟動失敗:', err.message); process.exit(1); });

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "llm-usage-dashboard",
+  "version": "0.1.0",
+  "description": "Local desktop dashboard for Codex (OpenAI) and Claude Code subscription usage, limits and cost",
+  "main": "src/main/main.js",
+  "bin": {
+    "llm-usage-dashboard": "bin/cli.js"
+  },
+  "author": "ianchen",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "claude",
+    "claude-code",
+    "openai",
+    "anthropic",
+    "usage",
+    "quota",
+    "rate-limit",
+    "dashboard",
+    "token",
+    "electron"
+  ],
+  "files": [
+    "src/**/*",
+    "assets/**/*",
+    "bin/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "electron .",
+    "probe": "node src/main/probe.js",
+    "icon": "node assets/genicon.js",
+    "pack": "node scripts/build-pack.js",
+    "dist": "electron-builder --win nsis portable"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "build": {
+    "appId": "com.ianchen.aiusagedashboard",
+    "productName": "AI Usage Dashboard",
+    "files": [
+      "src/**/*",
+      "assets/**/*",
+      "!**/*.map"
+    ],
+    "win": {
+      "target": [
+        { "target": "nsis", "arch": ["x64"] },
+        { "target": "portable", "arch": ["x64"] }
+      ],
+      "icon": "assets/icon.png"
+    },
+    "nsis": {
+      "oneClick": false,
+      "perMachine": false,
+      "allowToChangeInstallationDirectory": true,
+      "createDesktopShortcut": true,
+      "createStartMenuShortcut": true,
+      "shortcutName": "AI Usage Dashboard"
+    },
+    "portable": {
+      "artifactName": "AI-Usage-Dashboard-Portable-${version}.exe"
+    }
+  },
+  "dependencies": {
+    "electron": "^33.0.0"
+  },
+  "devDependencies": {
+    "@electron/packager": "^18.3.0",
+    "electron-builder": "^25.0.0"
+  }
+}

package/src/main/aggregate.js

@@ -0,0 +1,160 @@
+'use strict';
+// Aggregation engine: turns normalized usage events + Codex rate snapshot into
+// the dashboard data model (5h / weekly / monthly windows, per-project totals,
+// cost estimates, and a daily time series).
+const { costOf } = require('./pricing');
+const { projectLabel } = require('./paths');
+
+const FIVE_H = 5 * 3600 * 1000;
+const SEVEN_D = 7 * 86400 * 1000;
+
+function emptyAgg() {
+  return { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, total: 0, cost: 0, count: 0 };
+}
+
+function addEvent(agg, ev) {
+  agg.input += ev.tokens.input || 0;
+  agg.output += ev.tokens.output || 0;
+  agg.cacheWrite += ev.tokens.cacheWrite || 0;
+  agg.cacheRead += ev.tokens.cacheRead || 0;
+  agg.total += ev.tokens.total || 0;
+  agg.cost += costOf(ev.model, ev.tokens);
+  agg.count += 1;
+}
+
+function startOfMonth(now) {
+  const d = new Date(now);
+  return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+}
+function startOfDay(ms) {
+  const d = new Date(ms);
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+}
+
+// Reconstruct the current 5-hour activity block (ccusage-style) for events of
+// one provider. Returns { startMs, resetMs, agg } for the block containing now,
+// or null if no recent activity.
+function currentBlock(events, now) {
+  if (!events.length) return null;
+  const sorted = [...events].sort((a, b) => a.tsMs - b.tsMs);
+  let blockStart = null;
+  let lastTs = null;
+  let blockAgg = emptyAgg();
+  for (const ev of sorted) {
+    const floored = startOfHour(ev.tsMs);
+    if (
+      blockStart === null ||
+      ev.tsMs - blockStart >= FIVE_H ||
+      (lastTs !== null && ev.tsMs - lastTs >= FIVE_H)
+    ) {
+      blockStart = floored;
+      blockAgg = emptyAgg();
+    }
+    addEvent(blockAgg, ev);
+    lastTs = ev.tsMs;
+  }
+  const resetMs = blockStart + FIVE_H;
+  if (now >= resetMs) return null; // block already expired -> no active 5h usage
+  return { startMs: blockStart, resetMs, agg: blockAgg };
+}
+
+function startOfHour(ms) {
+  return Math.floor(ms / 3600000) * 3600000;
+}
+
+function windowAgg(events, fromMs, toMs) {
+  const agg = emptyAgg();
+  for (const ev of events) {
+    if (ev.tsMs >= fromMs && (toMs == null || ev.tsMs < toMs)) addEvent(agg, ev);
+  }
+  return agg;
+}
+
+function dailySeries(events, now, days) {
+  const buckets = [];
+  const todayStart = startOfDay(now);
+  for (let i = days - 1; i >= 0; i--) {
+    const dayStart = todayStart - i * 86400000;
+    buckets.push({ dayStart, label: new Date(dayStart).toISOString().slice(5, 10), total: 0, cost: 0 });
+  }
+  const first = buckets[0].dayStart;
+  for (const ev of events) {
+    if (ev.tsMs < first) continue;
+    const idx = Math.floor((startOfDay(ev.tsMs) - first) / 86400000);
+    if (idx >= 0 && idx < buckets.length) {
+      buckets[idx].total += ev.tokens.total || 0;
+      buckets[idx].cost += costOf(ev.model, ev.tokens);
+    }
+  }
+  return buckets;
+}
+
+function buildProvider(events, now, opts = {}) {
+  const monthStart = startOfMonth(now);
+  const block = currentBlock(events, now);
+  return {
+    window5h: block ? block.agg : emptyAgg(),
+    block5hResetMs: block ? block.resetMs : null,
+    weekly: windowAgg(events, now - SEVEN_D, null),
+    monthly: windowAgg(events, monthStart, null),
+    today: windowAgg(events, startOfDay(now), null),
+    allTime: windowAgg(events, 0, null),
+    daily: dailySeries(events, now, 14),
+    ...opts,
+  };
+}
+
+function buildProjects(allEvents, now) {
+  const monthStart = startOfMonth(now);
+  const map = new Map();
+  for (const ev of allEvents) {
+    let p = map.get(ev.project);
+    if (!p) {
+      p = {
+        project: ev.project,
+        label: projectLabel(ev.project),
+        all: emptyAgg(),
+        month: emptyAgg(),
+        byProvider: {},
+        lastTs: 0,
+      };
+      map.set(ev.project, p);
+    }
+    addEvent(p.all, ev);
+    if (ev.tsMs >= monthStart) addEvent(p.month, ev);
+    if (!p.byProvider[ev.provider]) p.byProvider[ev.provider] = emptyAgg();
+    addEvent(p.byProvider[ev.provider], ev);
+    if (ev.tsMs > p.lastTs) p.lastTs = ev.tsMs;
+  }
+  return Array.from(map.values()).sort((a, b) => b.all.total - a.all.total);
+}
+
+// codexRate: { primary, secondary, plan_type } from collector (used_percent etc.)
+function buildModel({ codex, claude, now = Date.now() }) {
+  const codexEvents = codex.events || [];
+  const claudeEvents = claude.events || [];
+  const all = [...codexEvents, ...claudeEvents];
+
+  const codexProvider = buildProvider(codexEvents, now, {
+    rate: codex.rate || null, // official 5h(primary)/weekly(secondary) percentages
+    planType: codex.planType || null,
+    fileCount: codex.fileCount || 0,
+  });
+  const claudeProvider = buildProvider(claudeEvents, now, {
+    subscription: claude.subscription || null,
+    fileCount: claude.fileCount || 0,
+  });
+
+  return {
+    generatedAt: now,
+    providers: { codex: codexProvider, claude: claudeProvider },
+    projects: buildProjects(all, now),
+    totals: {
+      monthCost: codexProvider.monthly.cost + claudeProvider.monthly.cost,
+      monthTokens: codexProvider.monthly.total + claudeProvider.monthly.total,
+      allCost: codexProvider.allTime.cost + claudeProvider.allTime.cost,
+    },
+  };
+}
+
+module.exports = { buildModel };

package/src/main/collectors/claude.js

@@ -0,0 +1,67 @@
+'use strict';
+// Claude Code collector.
+// Source: ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl (+ subagents/*.jsonl)
+//   assistant records: { type:"assistant", cwd, timestamp, requestId,
+//       message:{ id, model, usage:{ input_tokens, output_tokens,
+//                 cache_creation_input_tokens, cache_read_input_tokens } } }
+//
+// The same message is streamed across multiple lines; we de-duplicate by
+// requestId:messageId and keep the LAST occurrence (final cumulative usage),
+// mirroring ccusage's dedup strategy.
+const fs = require('fs');
+const { readJsonl, listJsonl } = require('./jsonl');
+const { CLAUDE_PROJECTS, CLAUDE_CREDS, normalizeCwd, exists } = require('../paths');
+
+function tokensFromClaude(u) {
+  return {
+    input: u.input_tokens || 0,
+    output: u.output_tokens || 0,
+    cacheWrite: u.cache_creation_input_tokens || 0,
+    cacheRead: u.cache_read_input_tokens || 0,
+    total:
+      (u.input_tokens || 0) +
+      (u.output_tokens || 0) +
+      (u.cache_creation_input_tokens || 0) +
+      (u.cache_read_input_tokens || 0),
+  };
+}
+
+function readSubscription() {
+  if (!exists(CLAUDE_CREDS)) return null;
+  try {
+    const d = JSON.parse(fs.readFileSync(CLAUDE_CREDS, 'utf8'));
+    const o = d.claudeAiOauth || {};
+    return { subscriptionType: o.subscriptionType || null, rateLimitTier: o.rateLimitTier || null };
+  } catch { return null; }
+}
+
+async function collectClaude() {
+  if (!exists(CLAUDE_PROJECTS)) return { events: [], subscription: null, fileCount: 0 };
+  const files = listJsonl(CLAUDE_PROJECTS);
+  // dedup map: key -> event (last write wins)
+  const dedup = new Map();
+
+  for (const file of files) {
+    await readJsonl(file, (o) => {
+      if (o.type !== 'assistant') return;
+      const msg = o.message;
+      if (!msg || !msg.usage) return;
+      const usage = msg.usage;
+      // skip synthetic/empty
+      const tk = tokensFromClaude(usage);
+      if (tk.total <= 0) return;
+      const key = `${o.requestId || ''}:${msg.id || ''}` || `${file}:${o.uuid}`;
+      dedup.set(key, {
+        provider: 'claude',
+        project: normalizeCwd(o.cwd),
+        model: msg.model || 'claude',
+        tsMs: Date.parse(o.timestamp) || 0,
+        tokens: tk,
+      });
+    });
+  }
+
+  return { events: Array.from(dedup.values()), subscription: readSubscription(), fileCount: files.length };
+}
+
+module.exports = { collectClaude };

package/src/main/collectors/codex.js

@@ -0,0 +1,73 @@
+'use strict';
+// Codex (OpenAI) collector.
+// Source: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+//   line 1: { type:"session_meta", payload:{ cwd, cli_version, model_provider } }
+//   token_count events: { type:"event_msg", payload:{ type:"token_count",
+//       info:{ last_token_usage{...}, total_token_usage{...} },
+//       rate_limits:{ primary{used_percent,window_minutes,resets_at}, secondary{...}, plan_type } } }
+//
+// We emit one normalized usage event per token_count (using last_token_usage =
+// the per-turn delta) and capture the globally newest rate_limits snapshot.
+const { readJsonl, listJsonl } = require('./jsonl');
+const { CODEX_SESSIONS, normalizeCwd } = require('../paths');
+
+// Codex config.toml default model is read for labeling; per-turn model is not in
+// the token_count event, so we approximate with the session model when known.
+function tokensFromCodex(u) {
+  if (!u) return null;
+  const cachedIn = u.cached_input_tokens || 0;
+  const inputAll = u.input_tokens || 0;
+  return {
+    input: Math.max(0, inputAll - cachedIn), // uncached input
+    cacheRead: cachedIn,
+    cacheWrite: 0, // codex does not separate cache writes
+    output: (u.output_tokens || 0) + (u.reasoning_output_tokens || 0),
+    total: u.total_tokens || (inputAll + (u.output_tokens || 0)),
+  };
+}
+
+async function collectCodex() {
+  const files = listJsonl(CODEX_SESSIONS);
+  const events = [];
+  let latestRate = null; // { tsMs, primary, secondary, plan_type }
+  let planType = null;
+
+  for (const file of files) {
+    let cwd = 'unknown';
+    let model = 'gpt-5'; // codex default family for pricing/label
+    await readJsonl(file, (o) => {
+      if (o.type === 'session_meta' && o.payload) {
+        cwd = normalizeCwd(o.payload.cwd);
+        return;
+      }
+      if (o.type === 'turn_context' && o.payload && o.payload.model) {
+        model = o.payload.model;
+        return;
+      }
+      if (o.type === 'event_msg' && o.payload && o.payload.type === 'token_count') {
+        const info = o.payload.info || {};
+        const tsMs = Date.parse(o.timestamp) || 0;
+        const tk = tokensFromCodex(info.last_token_usage);
+        if (tk && (tk.total > 0)) {
+          events.push({ provider: 'codex', project: cwd, model, tsMs, tokens: tk });
+        }
+        const rl = o.payload.rate_limits;
+        if (rl) {
+          if (rl.plan_type) planType = rl.plan_type;
+          if (!latestRate || tsMs > latestRate.tsMs) {
+            latestRate = {
+              tsMs,
+              primary: rl.primary || null,   // 5h window
+              secondary: rl.secondary || null, // weekly window
+              plan_type: rl.plan_type || null,
+            };
+          }
+        }
+      }
+    });
+  }
+
+  return { events, rate: latestRate, planType, fileCount: files.length };
+}
+
+module.exports = { collectCodex };

package/src/main/collectors/jsonl.js

@@ -0,0 +1,44 @@
+'use strict';
+// Stream a .jsonl file line-by-line, yielding parsed objects.
+// Tolerates blank/corrupt lines (skips them).
+const fs = require('fs');
+const readline = require('readline');
+
+async function readJsonl(filePath, onObj) {
+  await new Promise((resolve, reject) => {
+    let stream;
+    try {
+      stream = fs.createReadStream(filePath, { encoding: 'utf8' });
+    } catch (e) { return reject(e); }
+    stream.on('error', reject);
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    rl.on('line', (line) => {
+      const s = line.trim();
+      if (!s) return;
+      let obj;
+      try { obj = JSON.parse(s); } catch { return; }
+      try { onObj(obj); } catch { /* ignore handler errors per-line */ }
+    });
+    rl.on('close', resolve);
+    rl.on('error', reject);
+  });
+}
+
+// Recursively list *.jsonl files under a directory.
+function listJsonl(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = require('path').join(d, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(full);
+    }
+  }
+  return out;
+}
+
+module.exports = { readJsonl, listJsonl };