@its-clawdia/ocusage 1.0.1

package/README.md

@@ -0,0 +1,52 @@
+# ocusage
+
+OpenClaw Usage — cost analysis CLI for OpenClaw session logs.
+
+## Quick Start
+
+```bash
+# Run without installing
+npx ocusage@latest
+bunx ocusage@latest
+
+# Or install globally
+npm install -g ocusage
+```
+
+## Usage
+
+```
+ocusage [command] [options]
+
+Commands:
+  daily    (default) Aggregate costs by date
+  weekly   Aggregate costs by ISO week
+  monthly  Aggregate costs by month
+  session  Per-session breakdown
+
+Options:
+  --since YYYYMMDD    Filter sessions on or after this date
+  --until YYYYMMDD    Filter sessions on or before this date
+  --json              Output as JSON
+  --breakdown         Show per-model breakdown
+  --timezone TZ       Timezone for date grouping (default: local)
+  --path DIR          Custom session directory
+  --help, -h          Show help
+```
+
+## Examples
+
+```bash
+ocusage                     # Daily report
+ocusage daily               # Daily report
+ocusage monthly             # Monthly report
+ocusage weekly              # Weekly report
+ocusage session             # Per-session breakdown
+ocusage --since 20260301    # Filter from March 2026
+ocusage --json              # JSON output
+ocusage --breakdown         # Per-model cost breakdown
+```
+
+## Data Source
+
+Reads from `~/.openclaw/agents/main/sessions/*.jsonl` by default.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@its-clawdia/ocusage",
+  "version": "1.0.1",
+  "description": "CLI tool for analyzing OpenClaw token usage and costs from local session logs",
+  "type": "module",
+  "bin": {
+    "ocusage": "./src/cli.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "start": "node src/cli.js"
+  },
+  "keywords": [
+    "openclaw",
+    "usage",
+    "cost",
+    "analysis",
+    "tokens",
+    "llm",
+    "ai",
+    "cli"
+  ],
+  "author": "its-clawdia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/its-clawdia/ocusage.git"
+  },
+  "homepage": "https://github.com/its-clawdia/ocusage#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/aggregate.js

@@ -0,0 +1,122 @@
+/**
+ * aggregate.js — Group session data by time period and/or model
+ */
+
+import { getLocalDate, getISOWeek, getMonth } from './parser.js';
+
+/**
+ * Create an empty bucket for accumulating usage
+ */
+function emptyBucket(key) {
+  return {
+    key,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    sessions: 0,
+    models: new Set()
+  };
+}
+
+function addUsage(bucket, usage, model) {
+  bucket.input += usage.input;
+  bucket.output += usage.output;
+  bucket.cacheRead += usage.cacheRead;
+  bucket.cacheWrite += usage.cacheWrite;
+  bucket.totalTokens += usage.totalTokens;
+  bucket.cost.input += usage.cost.input;
+  bucket.cost.output += usage.cost.output;
+  bucket.cost.cacheRead += usage.cost.cacheRead;
+  bucket.cost.cacheWrite += usage.cost.cacheWrite;
+  bucket.cost.total += usage.cost.total;
+  if (model) bucket.models.add(model);
+}
+
+/**
+ * Aggregate sessions by a key function
+ * Returns sorted array of buckets
+ */
+export async function aggregateByPeriod(sessionIter, keyFn, { breakdown = false, timezone } = {}) {
+  const buckets = new Map(); // key -> bucket
+  const modelBuckets = new Map(); // `${key}::${model}` -> bucket
+
+  for await (const session of sessionIter) {
+    if (!session.timestamp) continue;
+    const date = getLocalDate(session.timestamp, timezone);
+    const key = keyFn(date);
+
+    // Ensure bucket exists
+    if (!buckets.has(key)) buckets.set(key, emptyBucket(key));
+    const bucket = buckets.get(key);
+    bucket.sessions++;
+
+    // Accumulate per-message usage
+    for (const msg of session.messages) {
+      addUsage(bucket, msg.usage, msg.model);
+
+      if (breakdown) {
+        const model = msg.model || 'unknown';
+        const mkey = `${key}::${model}`;
+        if (!modelBuckets.has(mkey)) modelBuckets.set(mkey, emptyBucket(model));
+        addUsage(modelBuckets.get(mkey), msg.usage, model);
+      }
+    }
+  }
+
+  // Finalize: convert Sets to arrays
+  const result = [...buckets.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, bucket]) => {
+      const r = { ...bucket, models: [...bucket.models] };
+      if (breakdown) {
+        r.breakdown = [...modelBuckets.entries()]
+          .filter(([k]) => k.startsWith(key + '::'))
+          .map(([k, b]) => ({ ...b, models: [...b.models] }))
+          .sort((a, b) => b.cost.total - a.cost.total);
+      }
+      return r;
+    });
+
+  return result;
+}
+
+/**
+ * Aggregate sessions per-session
+ */
+export async function aggregateBySessions(sessionIter, { breakdown = false, timezone } = {}) {
+  const sessions = [];
+
+  for await (const session of sessionIter) {
+    const date = session.timestamp ? getLocalDate(session.timestamp, timezone) : 'unknown';
+    const s = {
+      key: session.id.slice(0, 8),
+      id: session.id,
+      date,
+      models: session.models,
+      ...session.totals,
+      cost: { ...session.totals.cost }
+    };
+
+    if (breakdown) {
+      // Group by model within session
+      const modelMap = new Map();
+      for (const msg of session.messages) {
+        const model = msg.model || 'unknown';
+        if (!modelMap.has(model)) modelMap.set(model, emptyBucket(model));
+        addUsage(modelMap.get(model), msg.usage, model);
+      }
+      s.breakdown = [...modelMap.values()]
+        .map(b => ({ ...b, models: [...b.models] }))
+        .sort((a, b) => b.cost.total - a.cost.total);
+    }
+
+    sessions.push(s);
+  }
+
+  return sessions.sort((a, b) => a.date.localeCompare(b.date));
+}
+
+export { getISOWeek, getMonth };

package/src/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * cli.js — ocusage CLI entry point
+ */
+
+import { resolveSessionDir, parseAllSessions, getISOWeek, getMonth } from './parser.js';
+import { aggregateByPeriod, aggregateBySessions } from './aggregate.js';
+import { printPeriodReport, printSessionReport } from './format.js';
+
+// ─── Argument Parsing ───────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    command: 'daily',
+    since: null,
+    until: null,
+    json: false,
+    breakdown: false,
+    timezone: null,
+    path: null,
+    help: false,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    switch (arg) {
+      case 'daily':
+      case 'weekly':
+      case 'monthly':
+      case 'session':
+        opts.command = arg;
+        break;
+      case '--since':
+        opts.since = args[++i];
+        break;
+      case '--until':
+        opts.until = args[++i];
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '--breakdown':
+        opts.breakdown = true;
+        break;
+      case '--timezone':
+        opts.timezone = args[++i];
+        break;
+      case '--path':
+        opts.path = args[++i];
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      default:
+        if (!arg.startsWith('-')) {
+          // Assume it's a subcommand we don't know
+          console.error(`Unknown command: ${arg}`);
+        }
+    }
+    i++;
+  }
+
+  // Parse YYYYMMDD dates into YYYY-MM-DD
+  if (opts.since) {
+    opts.since = opts.since.replace(/^(\d{4})(\d{2})(\d{2})$/, '$1-$2-$3');
+  }
+  if (opts.until) {
+    opts.until = opts.until.replace(/^(\d{4})(\d{2})(\d{2})$/, '$1-$2-$3');
+  }
+
+  return opts;
+}
+
+// ─── Help ────────────────────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+ocusage — OpenClaw session cost analysis
+
+Usage:
+  ocusage [command] [options]
+
+Commands:
+  daily    (default) Aggregate costs by date
+  weekly   Aggregate costs by ISO week
+  monthly  Aggregate costs by month
+  session  Per-session breakdown
+
+Options:
+  --since YYYYMMDD    Filter sessions on or after this date
+  --until YYYYMMDD    Filter sessions on or before this date
+  --json              Output as JSON
+  --breakdown         Show per-model cost breakdown
+  --timezone TZ       Timezone for date grouping (e.g. America/Los_Angeles)
+  --path DIR          Custom session directory
+  --help, -h          Show this help
+
+Examples:
+  ocusage                        Daily cost report
+  ocusage monthly                Monthly summary
+  ocusage session --breakdown    Sessions with per-model breakdown
+  ocusage --since 20260301       Filter from March 1, 2026
+  ocusage --json | jq .          JSON output piped to jq
+`);
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const sessionDir = resolveSessionDir(opts.path);
+
+  const streamOpts = {
+    since: opts.since,
+    until: opts.until,
+    timezone: opts.timezone,
+  };
+
+  try {
+    let data;
+
+    if (opts.command === 'session') {
+      const sessionStream = parseAllSessions(sessionDir, streamOpts);
+      data = await aggregateBySessions(sessionStream, {
+        breakdown: opts.breakdown,
+        timezone: opts.timezone,
+      });
+    } else {
+      // Period-based aggregation
+      const keyFn = {
+        daily: (date) => date,
+        weekly: (date) => getISOWeek(date),
+        monthly: (date) => date.slice(0, 7),
+      }[opts.command] || ((date) => date);
+
+      const sessionStream = parseAllSessions(sessionDir, streamOpts);
+      data = await aggregateByPeriod(sessionStream, keyFn, {
+        breakdown: opts.breakdown,
+        timezone: opts.timezone,
+      });
+    }
+
+    if (opts.json) {
+      // Serialize (Sets are already converted to arrays in aggregation)
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+
+    if (opts.command === 'session') {
+      printSessionReport(data, { breakdown: opts.breakdown });
+    } else {
+      printPeriodReport(data, { mode: opts.command, breakdown: opts.breakdown });
+    }
+
+  } catch (err) {
+    console.error(`\nError: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/format.js

@@ -0,0 +1,276 @@
+/**
+ * format.js — Terminal table formatting with ANSI colors
+ */
+
+// ANSI color codes
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+  bgBlue: '\x1b[44m',
+  bgDark: '\x1b[48;5;235m',
+};
+
+function c(color, text) {
+  if (!process.stdout.isTTY) return text;
+  return C[color] + text + C.reset;
+}
+
+function bold(text) { return c('bold', text); }
+function dim(text) { return c('dim', text); }
+function gray(text) { return c('gray', text); }
+function cyan(text) { return c('cyan', text); }
+function green(text) { return c('green', text); }
+function yellow(text) { return c('yellow', text); }
+function blue(text) { return c('blue', text); }
+function magenta(text) { return c('magenta', text); }
+
+/**
+ * Format a number with commas
+ */
+function fmtNum(n) {
+  if (!n || n === 0) return gray('0');
+  return n.toLocaleString();
+}
+
+/**
+ * Format cost as $X.XXXX
+ */
+function fmtCost(n) {
+  if (!n || n === 0) return gray('$0.0000');
+  if (n < 0.001) return green(`$${n.toFixed(6)}`);
+  if (n < 1) return green(`$${n.toFixed(4)}`);
+  return yellow(`$${n.toFixed(4)}`);
+}
+
+/**
+ * Format token count compactly (e.g. 14.9k, 1.2M)
+ */
+function fmtTokens(n) {
+  if (!n || n === 0) return gray('0');
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+/**
+ * Pad string to width (accounting for ANSI escape codes)
+ */
+function visLen(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+function padEnd(str, width) {
+  const vl = visLen(str);
+  return str + ' '.repeat(Math.max(0, width - vl));
+}
+
+function padStart(str, width) {
+  const vl = visLen(str);
+  return ' '.repeat(Math.max(0, width - vl)) + str;
+}
+
+/**
+ * Render a table
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @param {'left'|'right'[]} aligns
+ */
+function renderTable(headers, rows, aligns) {
+  const allRows = [headers, ...rows];
+  const cols = headers.length;
+  const widths = Array(cols).fill(0);
+
+  for (const row of allRows) {
+    for (let i = 0; i < cols; i++) {
+      widths[i] = Math.max(widths[i], visLen(row[i] || ''));
+    }
+  }
+
+  const sep = gray('┼' + widths.map(w => '─'.repeat(w + 2)).join('┼') + '┼');
+  const topBorder = gray('┌' + widths.map(w => '─'.repeat(w + 2)).join('┬') + '┐');
+  const midBorder = gray('├' + widths.map(w => '─'.repeat(w + 2)).join('┼') + '┤');
+  const botBorder = gray('└' + widths.map(w => '─'.repeat(w + 2)).join('┴') + '┘');
+
+  function renderRow(row, isHeader = false) {
+    const cells = row.map((cell, i) => {
+      const align = aligns?.[i] || 'left';
+      const padded = align === 'right'
+        ? padStart(cell || '', widths[i])
+        : padEnd(cell || '', widths[i]);
+      return ` ${padded} `;
+    });
+    const line = gray('│') + cells.join(gray('│')) + gray('│');
+    return line;
+  }
+
+  const lines = [];
+  lines.push(topBorder);
+  lines.push(renderRow(headers.map(h => bold(cyan(h))), true));
+  lines.push(midBorder);
+
+  for (let i = 0; i < rows.length; i++) {
+    lines.push(renderRow(rows[i]));
+  }
+  lines.push(botBorder);
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the "Totals" summary footer
+ */
+function formatTotals(rows) {
+  let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, cost = 0;
+  for (const row of rows) {
+    input += row._input || 0;
+    output += row._output || 0;
+    cacheRead += row._cacheRead || 0;
+    cacheWrite += row._cacheWrite || 0;
+    cost += row._cost || 0;
+  }
+  return { input, output, cacheRead, cacheWrite, cost };
+}
+
+/**
+ * Print daily/weekly/monthly report
+ */
+export function printPeriodReport(data, { mode = 'daily', breakdown = false } = {}) {
+  if (data.length === 0) {
+    console.log(yellow('No data found.'));
+    return;
+  }
+
+  const title = { daily: 'Daily', weekly: 'Weekly', monthly: 'Monthly' }[mode] || 'Report';
+  console.log(bold(cyan(`\n  OpenClaw Usage — ${title} Report\n`)));
+
+  const headers = ['Period', 'Sessions', 'Input', 'Output', 'Cache↑', 'Cache↓', 'Total Tokens', 'Cost'];
+  const aligns = ['left', 'right', 'right', 'right', 'right', 'right', 'right', 'right'];
+  const rawRows = [];
+
+  let totalSessions = 0, totalInput = 0, totalOutput = 0;
+  let totalCacheR = 0, totalCacheW = 0, totalTokens = 0, totalCost = 0;
+
+  for (const d of data) {
+    rawRows.push([
+      bold(d.key),
+      fmtNum(d.sessions),
+      fmtTokens(d.input),
+      fmtTokens(d.output),
+      fmtTokens(d.cacheRead),
+      fmtTokens(d.cacheWrite),
+      fmtTokens(d.totalTokens),
+      fmtCost(d.cost.total),
+    ]);
+    totalSessions += d.sessions;
+    totalInput += d.input;
+    totalOutput += d.output;
+    totalCacheR += d.cacheRead;
+    totalCacheW += d.cacheWrite;
+    totalTokens += d.totalTokens;
+    totalCost += d.cost.total;
+  }
+
+  console.log(renderTable(headers, rawRows, aligns));
+
+  // Totals row
+  const totalsRow = [
+    bold(yellow('TOTAL')),
+    fmtNum(totalSessions),
+    fmtTokens(totalInput),
+    fmtTokens(totalOutput),
+    fmtTokens(totalCacheR),
+    fmtTokens(totalCacheW),
+    fmtTokens(totalTokens),
+    fmtCost(totalCost),
+  ];
+  console.log('\n' + bold('  Totals: ') +
+    `${fmtNum(totalSessions)} sessions  ·  ` +
+    `${fmtTokens(totalTokens)} tokens  ·  ` +
+    `${bold(fmtCost(totalCost))} total cost`);
+
+  if (breakdown) {
+    for (const d of data) {
+      if (!d.breakdown?.length) continue;
+      console.log(`\n  ${bold(cyan(d.key))} — model breakdown:`);
+      const bHeaders = ['Model', 'Input', 'Output', 'Cache↑', 'Cache↓', 'Cost'];
+      const bAligns = ['left', 'right', 'right', 'right', 'right', 'right'];
+      const bRows = d.breakdown.map(b => [
+        magenta(b.key),
+        fmtTokens(b.input),
+        fmtTokens(b.output),
+        fmtTokens(b.cacheRead),
+        fmtTokens(b.cacheWrite),
+        fmtCost(b.cost.total),
+      ]);
+      console.log(renderTable(bHeaders, bRows, bAligns));
+    }
+  }
+
+  console.log('');
+}
+
+/**
+ * Print session report
+ */
+export function printSessionReport(data, { breakdown = false } = {}) {
+  if (data.length === 0) {
+    console.log(yellow('No sessions found.'));
+    return;
+  }
+
+  console.log(bold(cyan('\n  OpenClaw Usage — Session Report\n')));
+
+  const headers = ['Session ID', 'Date', 'Models', 'Input', 'Output', 'Cache↑', 'Cache↓', 'Cost'];
+  const aligns = ['left', 'left', 'left', 'right', 'right', 'right', 'right', 'right'];
+
+  let totalCost = 0, totalTokens = 0;
+
+  const rows = data.map(s => {
+    totalCost += s.cost.total;
+    totalTokens += s.totalTokens;
+    return [
+      gray(s.key),
+      s.date,
+      magenta(s.models.slice(0, 2).map(m => m.replace('claude-', '')).join(', ') || 'unknown'),
+      fmtTokens(s.input),
+      fmtTokens(s.output),
+      fmtTokens(s.cacheRead),
+      fmtTokens(s.cacheWrite),
+      fmtCost(s.cost.total),
+    ];
+  });
+
+  console.log(renderTable(headers, rows, aligns));
+  console.log('\n' + bold('  Totals: ') +
+    `${data.length} sessions  ·  ` +
+    `${fmtTokens(totalTokens)} tokens  ·  ` +
+    `${bold(fmtCost(totalCost))} total cost`);
+
+  if (breakdown) {
+    for (const s of data) {
+      if (!s.breakdown?.length) continue;
+      console.log(`\n  Session ${gray(s.key)} (${s.date}) — model breakdown:`);
+      const bHeaders = ['Model', 'Input', 'Output', 'Cache↑', 'Cache↓', 'Cost'];
+      const bAligns = ['left', 'right', 'right', 'right', 'right', 'right'];
+      const bRows = s.breakdown.map(b => [
+        magenta(b.key),
+        fmtTokens(b.input),
+        fmtTokens(b.output),
+        fmtTokens(b.cacheRead),
+        fmtTokens(b.cacheWrite),
+        fmtCost(b.cost.total),
+      ]);
+      console.log(renderTable(bHeaders, bRows, bAligns));
+    }
+  }
+
+  console.log('');
+}

package/src/parser.js

@@ -0,0 +1,183 @@
+/**
+ * parser.js — Stream JSONL session files, extract usage data
+ */
+
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import os from 'os';
+
+const DEFAULT_SESSION_DIR = path.join(os.homedir(), '.openclaw', 'agents', 'main', 'sessions');
+
+/**
+ * Resolve session directory path
+ */
+export function resolveSessionDir(customPath) {
+  return customPath ? path.resolve(customPath) : DEFAULT_SESSION_DIR;
+}
+
+/**
+ * List all .jsonl session files in the directory (exclude .reset. files)
+ */
+export function listSessionFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.jsonl') && !f.includes('.reset.'))
+      .map(f => path.join(dir, f));
+  } catch (err) {
+    throw new Error(`Cannot read session directory: ${dir}\n${err.message}`);
+  }
+}
+
+/**
+ * Parse a single JSONL session file, yielding session data
+ * Returns: { id, timestamp, date, models, messages: [{timestamp, model, usage}] }
+ */
+export async function parseSessionFile(filePath) {
+  const session = {
+    id: path.basename(filePath, '.jsonl'),
+    filePath,
+    timestamp: null,
+    date: null,
+    models: new Set(),
+    currentModel: null,
+    messages: [],
+    totals: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+    }
+  };
+
+  const fileStream = fs.createReadStream(filePath, { encoding: 'utf8' });
+  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue; // skip malformed lines
+    }
+
+    switch (record.type) {
+      case 'session':
+        session.id = record.id || session.id;
+        session.timestamp = record.timestamp;
+        session.date = record.timestamp ? record.timestamp.slice(0, 10) : null;
+        break;
+
+      case 'model_change':
+        session.currentModel = record.modelId;
+        if (record.modelId) session.models.add(record.modelId);
+        break;
+
+      case 'message':
+        if (record.message?.role === 'assistant' && record.message?.usage) {
+          const usage = record.message.usage;
+          const model = record.message?.model || session.currentModel || 'unknown';
+          if (model) session.models.add(model);
+
+          const msg = {
+            timestamp: record.timestamp,
+            model,
+            usage: {
+              input: usage.input || 0,
+              output: usage.output || 0,
+              cacheRead: usage.cacheRead || 0,
+              cacheWrite: usage.cacheWrite || 0,
+              totalTokens: usage.totalTokens || 0,
+              cost: {
+                input: usage.cost?.input || 0,
+                output: usage.cost?.output || 0,
+                cacheRead: usage.cost?.cacheRead || 0,
+                cacheWrite: usage.cost?.cacheWrite || 0,
+                total: usage.cost?.total || 0
+              }
+            }
+          };
+
+          session.messages.push(msg);
+
+          // Accumulate totals
+          session.totals.input += msg.usage.input;
+          session.totals.output += msg.usage.output;
+          session.totals.cacheRead += msg.usage.cacheRead;
+          session.totals.cacheWrite += msg.usage.cacheWrite;
+          session.totals.totalTokens += msg.usage.totalTokens;
+          session.totals.cost.input += msg.usage.cost.input;
+          session.totals.cost.output += msg.usage.cost.output;
+          session.totals.cost.cacheRead += msg.usage.cost.cacheRead;
+          session.totals.cost.cacheWrite += msg.usage.cost.cacheWrite;
+          session.totals.cost.total += msg.usage.cost.total;
+        }
+        break;
+    }
+  }
+
+  session.models = [...session.models];
+  return session;
+}
+
+/**
+ * Parse all session files in parallel (with concurrency limit)
+ * Yields results as they complete
+ */
+export async function* parseAllSessions(sessionDir, { since, until, timezone } = {}) {
+  const files = listSessionFiles(sessionDir);
+
+  // Process in batches of 10 for parallelism
+  const BATCH = 10;
+  for (let i = 0; i < files.length; i += BATCH) {
+    const batch = files.slice(i, i + BATCH);
+    const results = await Promise.all(batch.map(parseSessionFile));
+    for (const session of results) {
+      if (!session.timestamp) continue;
+
+      // Date filtering
+      const sessionDate = getLocalDate(session.timestamp, timezone);
+      if (since && sessionDate < since) continue;
+      if (until && sessionDate > until) continue;
+
+      yield session;
+    }
+  }
+}
+
+/**
+ * Get YYYY-MM-DD for a timestamp in a given timezone
+ */
+export function getLocalDate(timestamp, timezone) {
+  const date = new Date(timestamp);
+  if (!timezone) {
+    // Local system time
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, '0');
+    const d = String(date.getDate()).padStart(2, '0');
+    return `${y}-${m}-${d}`;
+  }
+  return date.toLocaleDateString('en-CA', { timeZone: timezone }); // en-CA gives YYYY-MM-DD
+}
+
+/**
+ * Get ISO week string "YYYY-Www" for a date string "YYYY-MM-DD"
+ */
+export function getISOWeek(dateStr) {
+  const date = new Date(dateStr + 'T12:00:00Z');
+  const dayOfWeek = date.getUTCDay() || 7; // Monday=1, Sunday=7
+  date.setUTCDate(date.getUTCDate() + 4 - dayOfWeek);
+  const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+  const weekNo = Math.ceil(((date - yearStart) / 86400000 + 1) / 7);
+  return `${date.getUTCFullYear()}-W${String(weekNo).padStart(2, '0')}`;
+}
+
+/**
+ * Get "YYYY-MM" from "YYYY-MM-DD"
+ */
+export function getMonth(dateStr) {
+  return dateStr ? dateStr.slice(0, 7) : 'unknown';
+}